refactor: improve error messages

Author: mallardduck

pkg/teapot/dispatch.go

@@ -73,10 +73,20 @@ func (r *Router) Dispatch(method, pattern string, fn func(d *DispatchBuilder, m
 
 	// Conflict checks — catch problems early rather than letting chi panic
 	if _, exists := r.dispatchers[dispatcherKey]; exists {
-		panic(fmt.Sprintf("teapot: Dispatch conflicts with existing dispatcher for %s %s", method, fullPattern))
+		panic(fmt.Sprintf(
+			"teapot: duplicate dispatch registration\n\n"+
+				"  route:  %s %s\n"+
+				"  cause:  a Dispatch() or query-multiplexed route already owns this method+pattern\n"+
+				"  help:   consolidate all variants for this route into a single Dispatch() block",
+			method, fullPattern))
 	}
 	if _, exists := r.directRoutes[dispatcherKey]; exists {
-		panic(fmt.Sprintf("teapot: Dispatch conflicts with existing direct route for %s %s", method, fullPattern))
+		panic(fmt.Sprintf(
+			"teapot: duplicate route registration\n\n"+
+				"  route:  %s %s\n"+
+				"  cause:  a direct route (GET, POST, etc.) is already registered for this method+pattern\n"+
+				"  help:   remove the direct route, or replace both with a single Dispatch() block",
+			method, fullPattern))
 	}
 
 	db := &DispatchBuilder{
@@ -91,7 +101,12 @@ func (r *Router) Dispatch(method, pattern string, fn func(d *DispatchBuilder, m
 	// Validate that every route has a handler set
 	for _, cfg := range db.routes {
 		if cfg.handler == nil {
-			panic("teapot: Dispatch route missing handler — call Do() or pass handler to Default()")
+			panic(fmt.Sprintf(
+				"teapot: invalid dispatch route %q (%s): no handler configured\n"+
+					"hint: call Do(...) for this route or provide a handler via Default(...)",
+				cfg.name,
+				cfg.action,
+			))
 		}
 	}
 

pkg/teapot/router.go

@@ -57,7 +57,7 @@ func (rb *RouteBuilder) Name(name string) *RouteBuilder {
 		if existingName == fullName {
 			// Same name found - check if it's the same method
 			if existingRoute.Method == rb.route.Method {
-				panic(fmt.Sprintf("teapot: duplicate route %s:%s (existing: %s, new: %s)",
+				panic(fmt.Sprintf("teapot: duplicate route %s:%s pattern(existing: %s, new: %s)",
 					rb.route.Method, fullName, existingRoute.Pattern, rb.route.Pattern))
 			}
 
@@ -528,11 +528,11 @@ func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request) {
 func (r *Router) URL(name string, params ...string) (string, error) {
 	rt, exists := r.nameIndex[name]
 	if !exists {
-		return "", fmt.Errorf("route %q not found", name)
+		return "", fmt.Errorf("route %q not found — check that .Name() was called during registration", name)
 	}
 
 	if len(params)%2 != 0 {
-		return "", fmt.Errorf("params must be key-value pairs")
+		return "", fmt.Errorf("URL() for route %q: params must be key-value pairs, got %d arg(s)", name, len(params))
 	}
 
 	// Build parameter map

pkg/teapot/validation_test.go

@@ -20,7 +20,8 @@ func TestDuplicateRouteName(t *testing.T) {
 		} else {
 			msg := r.(string)
 			asserts.Contains(msg, "duplicate route")
-			asserts.Contains(msg, "GET:users")
+			asserts.Contains(msg, "GET")
+			asserts.Contains(msg, "users")
 		}
 	}()
 
@@ -51,8 +52,9 @@ func TestSameNameDifferentMethodsDifferentPath(t *testing.T) {
 			t.Error("expected panic for same name with different paths")
 		} else {
 			msg := r.(string)
-			asserts.Contains(msg, "used with different paths")
+			asserts.Contains(msg, "teapot: route name")
 			asserts.Contains(msg, "users.show")
+			asserts.Contains(msg, "used with different paths")
 		}
 	}()