caddyserver/caddy · error

setting up error subroutes: %v

Error message

setting up error subroutes: %v

What it means

Returned by Subroute.Provision when the error-handling routes (the 'errors' sub-route of a subroute) fail to provision. It is the error-chain counterpart of 'setting up subroutes' and only fires when sr.Routes provisioned fine but sr.Errors.Routes did not.

Source

Thrown at modules/caddyhttp/subroute.go:65

// 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)
	}
	return err
}

// Interface guards

View on GitHub (pinned to 50e54ee279)

Solutions

1. Inspect the wrapped error text to find the failing module in the errors.routes array
2. Verify the handler/matcher IDs exist in `caddy list-modules`
3. Simplify: remove the errors block to confirm the rest loads, then re-add it step by step
4. Regenerate the JSON from a working Caddyfile using `caddy adapt` to get canonical structure

Example fix

# before (caddyfile intent, broken JSON)
"errors": { "routes": [ { "handle": [{ "handler": "templatess" }] } ] }

# after
"errors": { "routes": [ { "handle": [{ "handler": "templates" }] } ] }

caddy validate --config Caddyfile  # exercises Provision/Validate incl. errors.routes

When it happens

Trigger: A JSON subroute with an 'errors' object whose 'routes' contain an invalid matcher or handler module; e.g. an error route referencing a handler that rejects its configuration during Provision.

Common situations: Converting a Caddyfile with 'handle_errors' to JSON and mis-editing it, adding custom error pages whose handler module is misspelled or missing from the build, or nesting unsupported matchers inside error routes.

Related errors

• server %s: setting up error handling routes: %v
• setting up subroutes: %v
• --input is required
• loading new config: %v
• loading storage module: %v

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