caddyserver/caddy · error

setting up subroutes: %v

Error message

setting up subroutes: %v

What it means

Returned by Subroute.Provision when provisioning the route list inside a subroute handler fails. The wrapped error comes from RouteList.Provision, which provisions each route's matcher sets and handlers, so the real cause is in the nested error string.

Source

Thrown at modules/caddyhttp/subroute.go:60

	// If the primary routes return an error, error handling
	// can be promoted to this configuration instead.
	Errors *HTTPErrorConfig `json:"errors,omitempty"`
}

// CaddyModule returns the Caddy module information.
func (Subroute) CaddyModule() caddy.ModuleInfo {
	return caddy.ModuleInfo{
		ID:  "http.handlers.subroute",
		New: func() caddy.Module { return new(Subroute) },
	}
}

// Provision sets up subrouting.
func (sr *Subroute) Provision(ctx caddy.Context) error {
	if sr.Routes != nil {
		err := sr.Routes.Provision(ctx)
		if err != nil {
			return fmt.Errorf("setting up subroutes: %v", err)
		}
		if sr.Errors != nil {
			err := sr.Errors.Routes.Provision(ctx)
			if err != nil {
				return fmt.Errorf("setting up error subroutes: %v", err)
			}
		}
	}
	return nil
}

func (sr *Subroute) ServeHTTP(w http.ResponseWriter, r *http.Request, next Handler) error {
	subroute := sr.Routes.Compile(next)
	err := subroute.ServeHTTP(w, r)
	if err != nil && sr.Errors != nil {
		r = sr.Errors.WithError(r, err)
		errRoute := sr.Errors.Routes.Compile(next)
		return errRoute.ServeHTTP(w, r)

View on GitHub (pinned to 50e54ee279)

Solutions

1. Read the wrapped error after the colon; it names the actual failing route/module
2. Validate module IDs against the running binary with `caddy list-modules`
3. Fix or remove the offending route in the subroute's routes array
4. If using a custom build, rebuild with the plugin that provides the missing module

Example fix

// before
{
  "handler": "subroute",
  "routes": [
    { "handle": [{ "handler": "rewrit", "path": "/new" }] }
  ]
}

// after
{
  "handler": "subroute",
  "routes": [
    { "handle": [{ "handler": "rewrite", "path": "/new" }] }
  ]
}

# validate config (and subroute module ids) before deploy
caddy validate --config Caddyfile --adapter caddyfile
caddy list-modules | grep -E '^http\.(handlers|matchers)\.' >/dev/null || echo 'unexpected module set'

When it happens

Trigger: A JSON config containing a 'http.handlers.subroute' module whose 'routes' array references an unknown module ID, a matcher module that fails provisioning, or a handler whose Provision returns an error. Occurs at config load/adapt time, before serving.

Common situations: Typos in module names inside a subroute, referencing a handler from a non-standard build not compiled in, malformed matcher syntax in imported Caddyfile snippets, or version mismatches after upgrading Caddy where a module changed its namespace.

Related errors

• setting up error subroutes: %v
• pki_root CA pool requires that a PKI app is configured: %v
• pki_intermediate CA pool requires that a PKI app is configur
• --input is required
• no metrics registry found

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