cloudflare/cloudflared · warning

request filtered by middleware handler (%s) due to: %s

Error message

request filtered by middleware handler (%s) due to: %s

What it means

This error (with a boolean 'true' indicating the response was already written) is returned by applyIngressMiddleware when an ingress middleware handler decides the request should be filtered. cloudflared writes the middleware's status code to the client (WriteRespHeaders) and aborts proxying to the origin. The middleware name and its reason are embedded in the message.

Source

Thrown at proxy/proxy.go:72

		originDialer: originDialer,
		tags:         tags,
		flowLimiter:  flowLimiter,
		log:          log,
	}

	return proxy
}

func (p *Proxy) applyIngressMiddleware(rule *ingress.Rule, r *http.Request, w connection.ResponseWriter) (error, bool) {
	for _, handler := range rule.Handlers {
		result, err := handler.Handle(r.Context(), r)
		if err != nil {
			return errors.Wrap(err, fmt.Sprintf("error while processing middleware handler %s", handler.Name())), false
		}

		if result.ShouldFilterRequest {
			_ = w.WriteRespHeaders(result.StatusCode, nil)
			return fmt.Errorf("request filtered by middleware handler (%s) due to: %s", handler.Name(), result.Reason), true
		}
	}
	return nil, true
}

// ProxyHTTP further depends on ingress rules to establish a connection with the origin service. This may be
// a simple roundtrip or a tcp/websocket dial depending on ingres rule setup.
func (p *Proxy) ProxyHTTP(
	w connection.ResponseWriter,
	tr *tracing.TracedHTTPRequest,
	isWebsocket bool,
) error {
	incrementRequests()
	defer decrementConcurrentRequests()

	req := tr.Request
	p.appendTagHeaders(req)
	_, ruleSpan := tr.Tracer().Start(req.Context(), "ingress_match",

View on GitHub (pinned to 2253eeeb25)

Solutions

  1. Read the 'due to:' reason and middleware name in the message to identify which rule rejected the request
  2. Adjust the offending middleware's configuration (allow-lists, rules) in the ingress config to permit legitimate traffic
  3. Verify client credentials/headers the middleware validates are being sent correctly
  4. If the request should never be filtered, check for stale remote-config rules overriding local ingress settings

Example fix

// before (ingress config)
// middleware rule blocks 10.0.0.0/8 entirely
// after
// add exception for the legitimate client
// rules: [{cidr: 10.1.2.3/32, allow: true}, {cidr: 10.0.0.0/8, allow: false}]
Defensive patterns

Strategy: try-catch

Validate before calling

// Simulate the middleware decision client-side before sending the request
for _, rule := range middlewareRules {
    if rule.ShouldFilter(clientIP, reqHeaders) {
        return fmt.Errorf("request would be filtered by %s: %s", rule.Name, rule.Reason)
    }
}

Try / catch

resp, err := doRequest(req)
if err != nil && strings.Contains(err.Error(), "request filtered by middleware handler") {
    var mwName, reason string
    fmt.Sscanf(err.Error(), "request filtered by middleware handler (%s) due to: %s", &mwName, &reason)
    log.Warn().Str("middleware", mwName).Str("reason", reason).Msg("request rejected pre-origin")
    return fmt.Errorf("blocked by %s: %s", mwName, reason)
}

Prevention

When it happens

Trigger: A middleware registered in the ingress configuration (e.g. access-control or blocklist style handlers) evaluates the request and returns result.ShouldFilterRequest == true, causing cloudflared to reject the request with result.StatusCode before reaching the origin service.

Common situations: See trigger scenarios.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/b1332c5bffcd9345. Report an issue: GitHub.