{"record":{"id":"e9d6229648dba7bc","repo":"caddyserver/caddy","slug":"server-s-setting-up-named-route-s-handlers","errorCode":null,"errorMessage":"server %s: setting up named route '%s' handlers: %v","messagePattern":"server (.+?): setting up named route '(.+?)' handlers: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/app.go","lineNumber":391,"sourceCode":"\t\t\t}\n\t\t\tprimaryRoute = srv.Routes.Compile(emptyHandler)\n\t\t}\n\t\tsrv.primaryHandlerChain = srv.wrapPrimaryRoute(primaryRoute)\n\n\t\t// pre-compile the error handler chain\n\t\tif srv.Errors != nil {\n\t\t\terr := srv.Errors.Routes.Provision(ctx)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"server %s: setting up error handling routes: %v\", srvName, err)\n\t\t\t}\n\t\t\tsrv.errorHandlerChain = srv.Errors.Routes.Compile(errorEmptyHandler)\n\t\t}\n\n\t\t// provision the named routes (they get compiled at runtime)\n\t\tfor name, route := range srv.NamedRoutes {\n\t\t\terr := route.Provision(ctx, app.Metrics)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"server %s: setting up named route '%s' handlers: %v\", name, srvName, err)\n\t\t\t}\n\t\t}\n\n\t\t// prepare the TLS connection policies\n\t\terr = srv.TLSConnPolicies.Provision(ctx)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"server %s: setting up TLS connection policies: %v\", srvName, err)\n\t\t}\n\n\t\t// if there is no idle timeout, set a sane default; users have complained\n\t\t// before that aggressive CDNs leave connections open until the server\n\t\t// closes them, so if we don't close them it leads to resource exhaustion\n\t\tif srv.IdleTimeout == 0 {\n\t\t\tsrv.IdleTimeout = defaultIdleTimeout\n\t\t}\n\t\tif srv.ReadHeaderTimeout == 0 {\n\t\t\tsrv.ReadHeaderTimeout = defaultReadHeaderTimeout // see #6663\n\t\t}","sourceCodeStart":373,"sourceCodeEnd":409,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/app.go#L373-L409","documentation":"Named routes (servers.<name>.named_routes, compiled on demand at runtime) are provisioned during app provisioning. If any named route's matchers or handlers fail, this error fires. Note: as of this code the format arguments are swapped — the message prints the route name in the 'server %s' slot and the server name in the '%s' route slot, so read it accordingly.","triggerScenarios":"A route under servers.<name>.named_routes.<name> whose handler or matcher module fails to provision, e.g. a malformed respond or reverse_proxy block, or a reference to an undefined named route.","commonSituations":"Defining reusable named routes (invoke/named_route) and mistyping the route body; refactoring shared snippets between Caddyfile sites.","solutions":["Look past the swapped labels: identify the failing route from the wrapped error text","Fix that named route's matchers/handlers","Prefer `caddy validate` to iterate quickly without starting the server"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"for name, r := range srvCfg.NamedRoutes {\n    if r == nil || len(r.HandlersRaw) == 0 && len(r.MatchersRaw) == 0 {\n        return fmt.Errorf(\"named route %q is empty\", name)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Define named routes before any invoke references them","Note the swapped server/route labels in this message; rely on the wrapped cause text"],"tags":["caddy","http","named-routes","provisioning","config"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}