caddyserver/caddy · error

server %s: setting up error handling routes: %v

Error message

server %s: setting up error handling routes: %v

What it means

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.

Source

Thrown at modules/caddyhttp/app.go:382

		}

		// pre-compile the primary handler chain, and be sure to wrap it in our
		// route handler so that important security checks are done, etc.
		primaryRoute := emptyHandler
		if srv.Routes != nil {
			err := srv.Routes.ProvisionHandlers(ctx, app.Metrics)
			if err != nil {
				return fmt.Errorf("server %s: setting up route handlers: %v", srvName, err)
			}
			primaryRoute = srv.Routes.Compile(emptyHandler)
		}
		srv.primaryHandlerChain = srv.wrapPrimaryRoute(primaryRoute)

		// pre-compile the error handler chain
		if srv.Errors != nil {
			err := srv.Errors.Routes.Provision(ctx)
			if err != nil {
				return fmt.Errorf("server %s: setting up error handling routes: %v", srvName, err)
			}
			srv.errorHandlerChain = srv.Errors.Routes.Compile(errorEmptyHandler)
		}

		// provision the named routes (they get compiled at runtime)
		for name, route := range srv.NamedRoutes {
			err := route.Provision(ctx, app.Metrics)
			if err != nil {
				return fmt.Errorf("server %s: setting up named route '%s' handlers: %v", name, srvName, err)
			}
		}

		// prepare the TLS connection policies
		err = srv.TLSConnPolicies.Provision(ctx)
		if err != nil {
			return fmt.Errorf("server %s: setting up TLS connection policies: %v", srvName, err)
		}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Inspect the wrapped error for the failing matcher/handler inside the errors block
2. Fix the entry (module ID, options, named-route reference)
3. Validate with `caddy validate` after the change

if err := caddy.Validate(cfgJSON); err != nil { return err } // covers errors.routes provisioning

When it happens

Trigger: 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.

Common situations: Configuring custom error handling with handlers copied from the main routes but missing required fields; referencing named routes before defining them.

Related errors

• server %s: %v
• server %s: setting up route handlers: %v
• server %s: setting up named route '%s' handlers: %v
• unknown object ID '%s'
• loading new config: %v

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