caddyserver/caddy · error · retryableResponseError

upstream response matched retry_match (status %d)

Error message

upstream response matched retry_match (status %d)

What it means

Error "upstream response matched retry_match (status %d)" thrown in caddyserver/caddy.

Source

Thrown at modules/caddyhttp/reverseproxy/reverseproxy.go:1145

	// that contain at least one expression matcher, since those are
	// the ones that can reference response data ({rp.status_code},
	// {rp.header.*}). Pure request-only matchers (method, path, etc.)
	// are skipped to avoid retrying every response that matches a
	// request condition
	if h.LoadBalancing != nil && len(h.LoadBalancing.RetryMatch) > 0 {
		for _, matcherSet := range h.LoadBalancing.RetryMatch {
			if !matcherSetHasExpressionMatcher(matcherSet) {
				continue
			}
			match, err := matcherSet.MatchWithError(req)
			if err != nil {
				h.logger.Error("error matching request for retry", zap.Error(err))
				break
			}
			if match {
				res.Body.Close()
				return retryableResponseError{
					error:      fmt.Errorf("upstream response matched retry_match (status %d)", res.StatusCode),
					statusCode: res.StatusCode,
				}
			}
		}
	}

	// see if any response handler is configured for this response from the backend
	for i, rh := range h.HandleResponse {
		if rh.Match != nil && !rh.Match.Match(res.StatusCode, res.Header) {
			continue
		}

		// if configured to only change the status code,
		// do that then continue regular proxy response
		if statusCodeStr := rh.StatusCode.String(); statusCodeStr != "" {
			statusCode, err := strconv.Atoi(repl.ReplaceAll(statusCodeStr, ""))
			if err != nil {
				return caddyhttp.Error(http.StatusInternalServerError, err)

View on GitHub (pinned to 50e54ee279)

Solutions

1. Adjust the retry_match criteria or fix the upstream so it does not return the matched status, if retries are not desired.

When it happens

Trigger: Thrown at modules/caddyhttp/reverseproxy/reverseproxy.go:1145 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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