caddyserver/caddy · error

provisioning response handler %d: %w

Error message

provisioning response handler %d: %w

What it means

Returned by Intercept.Provision when provisioning one of the configured handle_response entries fails; the inner error is wrapped with the 0-based index of the failing response handler. The Intercept module (EXPERIMENTAL) runs routes against buffered responses, and each handle_response route must itself provision successfully.

Source

Thrown at modules/caddyhttp/intercept/intercept.go:85

// CaddyModule returns the Caddy module information.
//
// EXPERIMENTAL: Subject to change or removal.
func (Intercept) CaddyModule() caddy.ModuleInfo {
	return caddy.ModuleInfo{
		ID:  "http.handlers.intercept",
		New: func() caddy.Module { return new(Intercept) },
	}
}

// Provision ensures that i is set up properly before use.
//
// EXPERIMENTAL: Subject to change or removal.
func (irh *Intercept) Provision(ctx caddy.Context) error {
	// set up any response routes
	for i, rh := range irh.HandleResponse {
		err := rh.Provision(ctx)
		if err != nil {
			return fmt.Errorf("provisioning response handler %d: %w", i, err)
		}
	}

	irh.logger = ctx.Logger()

	return nil
}

var bufPool = sync.Pool{
	New: func() any {
		return new(bytes.Buffer)
	},
}

// EXPERIMENTAL: Subject to change or removal.
type interceptedResponseHandler struct {
	caddyhttp.ResponseRecorder
	replacer     *caddy.Replacer

View on GitHub (pinned to 50e54ee279)

Solutions

1. Use the index in the message to find the exact handle_response block (0-based) in your config and inspect the wrapped error for the root cause.
2. Fix or simplify the nested route — often a matcher typo or unsupported handler inside the response route.
3. Because intercept is experimental, align config syntax with your Caddy version's docs; adjust after upgrades.
4. Test with `caddy adapt` then `caddy validate` to isolate the failing block.

Example fix

# before
intercept {
    @not_found status 404
    handle_response @not_found {
        rewrite * /not-found
        bad_directive "oops"
    }
}
# after
intercept {
    @not_found status 404
    handle_response @not_found {
        rewrite * /not-found
        file_server
    }
}

# Adapt + validate in CI so a broken handle_response block fails before deploy
caddy adapt --config Caddyfile --pretty > /dev/null || exit 1
caddy validate --adapted-config <(caddy adapt --config Caddyfile) || exit 1

When it happens

Trigger: Configuring `intercept` with `@matcher handle_response ...` blocks where one of the response routes contains an invalid nested handler/matcher — e.g. a bad matcher syntax or a handler module that fails its own Provision; the index in the message tells you which block.

Common situations: Using intercept with replace_error/handle_response patterns; a nested module that errors during provisioning (bad args); experimental API churn between Caddy versions breaking older configs.

Related errors

• --input is required
• loading new config: %v
• loading storage module: %v
• %v; additionally, cleanup: %v
• provision %s: %v

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