{"record":{"id":"46b66b9e1d57cd23","repo":"caddyserver/caddy","slug":"invoke-route-s-not-found","errorCode":null,"errorMessage":"invoke: route '%s' not found","messagePattern":"invoke: route '(.+?)' not found","errorType":"http","errorClass":null,"httpStatus":500,"severity":"error","filePath":"modules/caddyhttp/invoke.go","lineNumber":50,"sourceCode":"type Invoke struct {\n\t// Name is the key of the named route to execute\n\tName string `json:\"name,omitempty\"`\n}\n\n// CaddyModule returns the Caddy module information.\nfunc (Invoke) CaddyModule() caddy.ModuleInfo {\n\treturn caddy.ModuleInfo{\n\t\tID:  \"http.handlers.invoke\",\n\t\tNew: func() caddy.Module { return new(Invoke) },\n\t}\n}\n\nfunc (invoke *Invoke) ServeHTTP(w http.ResponseWriter, r *http.Request, next Handler) error {\n\tserver := r.Context().Value(ServerCtxKey).(*Server)\n\tif route, ok := server.NamedRoutes[invoke.Name]; ok {\n\t\treturn route.Compile(next).ServeHTTP(w, r)\n\t}\n\treturn fmt.Errorf(\"invoke: route '%s' not found\", invoke.Name)\n}\n\n// Interface guards\nvar (\n\t_ MiddlewareHandler = (*Invoke)(nil)\n)\n","sourceCodeStart":32,"sourceCodeEnd":57,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/invoke.go#L32-L57","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Define the named route in the same server, e.g. `&myroute { ... }` block or the named routes section, matching the invoke name exactly.","Check spelling and case — names are exact strings.","If routes are shared across servers, define the named route in each server or use a global snippet + import instead.","Validate with `caddy adapt` and inspect the JSON to confirm the named route landed under the right server."],"exampleFix":"# before\nroute {\n    invoke cache\n}\n# after\n&cache {\n    uri strip_prefix /assets\n    file_server\n}\nroute {\n    invoke cache\n}","handlingStrategy":"validation","validationCode":"# CI check: every invoked route name must be defined in the same server block\ninvoked=$(grep -oE 'invoke\\s+\\S+' Caddyfile | awk '{print $2}' | sort -u)\ndefined=$(grep -oE '^&(\\S+)' Caddyfile | tr -d '&' | sort -u)\nfor n in $invoked; do\n  echo \"$defined\" | grep -qx \"$n\" || { echo \"invoke target '$n' has no named route\"; exit 1; }\ndone","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Define named routes with &name blocks in the same server that invokes them.","Treat route names as API contracts — rename via search/replace across the whole file.","Run `caddy adapt` and inspect the JSON 'routes' to confirm named routes resolved."],"tags":["caddy","invoke","named-routes","routing","config"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}