caddyserver/caddy · error

route %d: %v

Error message

route %d: %v

What it means

Aggregation error from RouteList.ProvisionMatchers: it provisions matchers for every route in a list and, on the first failure, returns the failing route's 0-based index with the underlying error. It is purely positional context — the real problem is in the wrapped matcher-loading error (see 524).

Source

Thrown at modules/caddyhttp/routes.go:215

// Provision sets up both the matchers and handlers in the routes.
func (routes RouteList) Provision(ctx caddy.Context) error {
	err := routes.ProvisionMatchers(ctx)
	if err != nil {
		return err
	}
	return routes.ProvisionHandlers(ctx, nil)
}

// ProvisionMatchers sets up all the matchers by loading the
// matcher modules. Only call this method directly if you need
// to set up matchers and handlers separately without having
// to provision a second time; otherwise use Provision instead.
func (routes RouteList) ProvisionMatchers(ctx caddy.Context) error {
	for i := range routes {
		err := routes[i].ProvisionMatchers(ctx)
		if err != nil {
			return fmt.Errorf("route %d: %v", i, err)
		}
	}
	return nil
}

// ProvisionHandlers sets up all the handlers by loading the
// handler modules. Only call this method directly if you need
// to set up matchers and handlers separately without having
// to provision a second time; otherwise use Provision instead.
func (routes RouteList) ProvisionHandlers(ctx caddy.Context, metrics *Metrics) error {
	for i := range routes {
		err := routes[i].ProvisionHandlers(ctx, metrics)
		if err != nil {
			return fmt.Errorf("route %d: %v", i, err)
		}
	}
	return nil
}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Use the reported route index to locate the offending entry in the routes array
2. Follow the wrapped error to fix the specific matcher (unknown name, bad value)
3. Re-run 'caddy adapt' then 'caddy validate' on the fixed config

// nothing route-specific; validate whole config:
// caddy validate --config Caddyfile --adapter caddyfile
// The 'route %d:' prefix then maps directly to the index in the JSON routes array.

When it happens

Trigger: A subroute or route array where route N has an invalid/unknown matcher; provisioning stops at the first bad route and reports its index.

Common situations: Large generated route tables (e.g. from caddyfile adaptation of many site blocks) where one block has a bad matcher; the index tells you which block to fix.

Related errors

• loading matcher modules: %v
• server %s: setting up route matchers: %v
• invoke: route '%s' not found
• loading handler modules: %v
• request path is missing object ID

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