caddyserver/caddy · error

invoke: route '%s' not found

Error message

invoke: route '%s' not found

What it means

Returned by the Invoke handler at request time: it looks up invoke.Name in the current server's NamedRoutes map, and the named route does not exist. Named routes are defined at the server level (named_router / route blocks with a name) and invoke dereferences them; an unknown name fails every request that hits the handler.

Source

Thrown at modules/caddyhttp/invoke.go:50

type Invoke struct {
	// Name is the key of the named route to execute
	Name string `json:"name,omitempty"`
}

// CaddyModule returns the Caddy module information.
func (Invoke) CaddyModule() caddy.ModuleInfo {
	return caddy.ModuleInfo{
		ID:  "http.handlers.invoke",
		New: func() caddy.Module { return new(Invoke) },
	}
}

func (invoke *Invoke) ServeHTTP(w http.ResponseWriter, r *http.Request, next Handler) error {
	server := r.Context().Value(ServerCtxKey).(*Server)
	if route, ok := server.NamedRoutes[invoke.Name]; ok {
		return route.Compile(next).ServeHTTP(w, r)
	}
	return fmt.Errorf("invoke: route '%s' not found", invoke.Name)
}

// Interface guards
var (
	_ MiddlewareHandler = (*Invoke)(nil)
)

View on GitHub (pinned to 50e54ee279)

Solutions

1. Define the named route in the same server, e.g. `&myroute { ... }` block or the named routes section, matching the invoke name exactly.
2. Check spelling and case — names are exact strings.
3. If routes are shared across servers, define the named route in each server or use a global snippet + import instead.
4. Validate with `caddy adapt` and inspect the JSON to confirm the named route landed under the right server.

Example fix

# before
route {
    invoke cache
}
# after
&cache {
    uri strip_prefix /assets
    file_server
}
route {
    invoke cache
}

# CI check: every invoked route name must be defined in the same server block
invoked=$(grep -oE 'invoke\s+\S+' Caddyfile | awk '{print $2}' | sort -u)
defined=$(grep -oE '^&(\S+)' Caddyfile | tr -d '&' | sort -u)
for n in $invoked; do
  echo "$defined" | grep -qx "$n" || { echo "invoke target '$n' has no named route"; exit 1; }
done

When it happens

Trigger: Configuring `invoke myroute` (or JSON "invoke": {"name": "myroute"}) when no route named myroute is defined under the same server's routes/named routes — due to typo, defining the route in a different server block, or forgetting to name the route.

Common situations: Refactoring shared snippets into named routes and missing the definition; the same Caddy config serving multiple server blocks where the route exists only in one; version differences in the named-routes feature (experimental syntax changes).

Related errors

• server %s: setting up named route '%s' handlers: %v
• loading matcher modules: %v
• loading handler modules: %v
• route %d: %v
• request path is missing object ID

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/46b66b9e1d57cd23. Report an issue: GitHub.