caddyserver/caddy · error

server %s: setting up named route '%s' handlers: %v

Error message

server %s: setting up named route '%s' handlers: %v

What it means

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.

Source

Thrown at modules/caddyhttp/app.go:391

			}
			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)
		}

		// if there is no idle timeout, set a sane default; users have complained
		// before that aggressive CDNs leave connections open until the server
		// closes them, so if we don't close them it leads to resource exhaustion
		if srv.IdleTimeout == 0 {
			srv.IdleTimeout = defaultIdleTimeout
		}
		if srv.ReadHeaderTimeout == 0 {
			srv.ReadHeaderTimeout = defaultReadHeaderTimeout // see #6663
		}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Look past the swapped labels: identify the failing route from the wrapped error text
2. Fix that named route's matchers/handlers
3. Prefer `caddy validate` to iterate quickly without starting the server

for name, r := range srvCfg.NamedRoutes {
    if r == nil || len(r.HandlersRaw) == 0 && len(r.MatchersRaw) == 0 {
        return fmt.Errorf("named route %q is empty", name)
    }
}

When it happens

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

Common situations: Defining reusable named routes (invoke/named_route) and mistyping the route body; refactoring shared snippets between Caddyfile sites.

Related errors

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

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