{"record":{"id":"4eb7dedad68ae588","repo":"caddyserver/caddy","slug":"server-s-setting-up-error-handling-routes-v","errorCode":null,"errorMessage":"server %s: setting up error handling routes: %v","messagePattern":"server (.+?): setting up error handling routes: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/app.go","lineNumber":382,"sourceCode":"\t\t}\n\n\t\t// pre-compile the primary handler chain, and be sure to wrap it in our\n\t\t// route handler so that important security checks are done, etc.\n\t\tprimaryRoute := emptyHandler\n\t\tif srv.Routes != nil {\n\t\t\terr := srv.Routes.ProvisionHandlers(ctx, app.Metrics)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"server %s: setting up route handlers: %v\", srvName, err)\n\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","sourceCodeStart":364,"sourceCodeEnd":400,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/app.go#L364-L400","documentation":"The error-routing chain (servers.<name>.errors.routes) is provisioned after the primary chain. If any matcher or handler inside the errors block fails to provision, this error names the server and wraps the cause. Error routes use the same Route Provision path, so the same module rules apply.","triggerScenarios":"A handler or matcher under servers.<name>.errors.routes that is unknown, misconfigured, or fails its Provision — e.g. an error_route referencing a template with bad syntax, or a named route that does not exist.","commonSituations":"Configuring custom error handling with handlers copied from the main routes but missing required fields; referencing named routes before defining them.","solutions":["Inspect the wrapped error for the failing matcher/handler inside the errors block","Fix the entry (module ID, options, named-route reference)","Validate with `caddy validate` after the change"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if err := caddy.Validate(cfgJSON); err != nil { return err } // covers errors.routes provisioning","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep error-route handlers as simple as possible (respond/templates)","Test error pages by triggering 502s in a staging environment after config changes"],"tags":["caddy","http","error-handling","provisioning","config"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}