Troubleshooting CORS at the Proxy Layer

A CORS error whose root cause is not in your application is one of the most disorienting failures to debug: your server code emits Access-Control-Allow-Origin correctly, your unit tests pass, curl against localhost looks perfect — yet the browser still reports the request as blocked. The reason is that between your application and the browser sits at least one intermediary — a reverse proxy, an application load balancer, a CDN, an API gateway, or a service-mesh sidecar — and any of them can strip, duplicate, or drop the very headers CORS depends on. Because the browser performs an exact string comparison on the headers it actually receives, a header that was correct at the origin but mutated in transit fails identically to one that was never sent.

This page is part of Cross-Origin Debugging & Error Diagnosis, which covers reading browser errors, inspecting preflight in DevTools, and reproducing failures with curl. Here the focus narrows to the network path itself: how to prove an intermediary is at fault, and how to fix the specific layer responsible.

The Problem: Correct Headers That Never Arrive

The WHATWG Fetch Standard (§3.2, CORS check) defines the browser’s decision as a comparison against the Access-Control-Allow-Origin value present on the response it receives. The specification says nothing about how many hops the response crossed — it only sees the final headers. This creates a class of failures that are invisible from the application’s perspective:

• A header the application set is stripped by a proxy that does not forward unknown response headers.
• A header the application set is duplicated because a second layer adds its own copy, producing Access-Control-Allow-Origin: https://app.example.com, https://app.example.com — which the browser rejects because only one value is allowed.
• A header is present on 200 but dropped on 4xx/5xx because of Nginx’s add_header behaviour without the always flag.
• The preflight OPTIONS request is blocked outright by a WAF before the application ever sees it, returning 403 in place of the expected 204.

The unifying symptom: the failure follows the deployment topology, not the code. It reproduces through the proxy and vanishes when you hit the origin directly. That asymmetry is both the diagnosis and the fix strategy.

Spec Anchor: What the Network Path Must Preserve

Per the Fetch Standard’s CORS-preflight fetch (§4.8) and the CORS check (§3.2), the response the browser evaluates must carry, unchanged from the origin’s intent:

• Access-Control-Allow-Origin — exactly one value, matching the request’s Origin or * (never * with credentials).
• Access-Control-Allow-Methods and Access-Control-Allow-Headers — on the preflight response, covering the declared method and headers.
• Access-Control-Allow-Credentials: true — when the request is credentialed, on both the preflight and the actual response.
• Vary: Origin — so that shared caches key responses per origin rather than serving one origin’s grant to another.

Every intermediary is obligated either to pass these through untouched or to synthesise a complete, correct set itself. A layer that does neither — passing some through while overwriting or dropping others — is the source of most proxy-layer CORS bugs.

Reference: Proxy-Layer Failure Modes

Where Headers Get Mutated Along the Path

The diagram traces a request from the browser through a typical multi-layer path — CDN, load balancer, reverse proxy, application — and marks the two points where CORS headers are most often lost or duplicated.

Step-by-Step: Bisect the Path, Then Fix the Layer

Step 1 — Confirm the Origin Is Correct

Reach the application directly, bypassing every proxy. Use --resolve or an internal address so DNS does not send you back through the CDN:

# Hit the app's own listener directly (internal IP or --resolve override)
curl -sS -D - -o /dev/null \
  --resolve api.example.com:8080:10.0.3.14 \
  -X OPTIONS "http://api.example.com:8080/v1/resource" \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: authorization, content-type"

Confirm the origin returns Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Headers. If they are missing here, the problem is in the application, not the proxy — start with Server-Side CORS Configuration & Header Management.

Step 2 — Reproduce Through the Public Edge

Run the identical request against the public hostname that traverses the full proxy stack:

curl -sS -D - -o /dev/null \
  -X OPTIONS "https://api.example.com/v1/resource" \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: authorization, content-type"

Diff the two responses. A missing header means a layer stripped it; two copies mean a layer duplicated it; a 403 means a WAF blocked the OPTIONS. For a deeper treatment of building these requests, see Reproducing CORS Failures with curl.

Step 3 — Walk Inward to Isolate the Hop

If the edge and origin disagree, test each intermediate layer’s own address in turn — load balancer, then reverse proxy — using --resolve to pin each hop. The first layer whose outbound headers differ from its inbound headers is the offender. Server-identifying response headers (for example a backend Server: value that should not survive edge termination) and per-hop request IDs help you confirm which layer answered.

Step 4 — Fix Nginx add_header Drops on Errors

If headers appear on 200 but vanish on 4xx/5xx, add the always flag. Without it, Nginx omits add_header output for error status codes:

location /v1/ {
  proxy_pass http://backend_upstream;

  # `always` emits the header on every status, including 4xx/5xx
  add_header Access-Control-Allow-Origin  $cors_origin always;
  add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
  add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
  add_header Vary                         "Origin" always;
}

Step 5 — Resolve Double CORS (ALB + App)

If two layers each add Access-Control-Allow-Origin, disable it on one. Keep CORS on the layer that can allowlist-match the Origin, and strip the other layer’s copy so no duplicate survives:

location /v1/ {
  proxy_pass http://backend_upstream;

  # Remove the app's CORS headers so only the proxy's copy remains
  proxy_hide_header Access-Control-Allow-Origin;
  proxy_hide_header Access-Control-Allow-Credentials;

  add_header Access-Control-Allow-Origin      $cors_origin always;
  add_header Access-Control-Allow-Credentials "true" always;
  add_header Vary "Origin" always;
}

The full walkthrough of the duplicate case lives in Fixing Duplicate Access-Control-Allow-Origin Headers.

Step 6 — Add a WAF Exception for OPTIONS

If the preflight returns 403, the WAF rejected OPTIONS before routing. Add a scoped exception that allows OPTIONS on the API path prefix while leaving other methods governed by the rule set. On a managed edge such as Cloudflare, this is a WAF skip rule; the Cloudflare-specific procedure is in Debugging CORS Failures Behind Cloudflare.

Edge Cases and Security Boundaries

Do not “fix” a stripped header by reflecting every origin. The temptation when a proxy drops Access-Control-Allow-Origin is to have the proxy echo $http_origin unconditionally. That turns the API into one that trusts any browser page. Reflect only allowlist-matched origins; see Dynamic Origin Validation Patterns and Wildcard Risks & Mitigation.

The null origin appears from sandboxed iframes, data: URLs, and some redirects. A proxy that reflects it grants those contexts access. Treat null as unmatched unless you deliberately support such flows.

Credentialed requests forbid *. If a layer downgrades an exact origin to Access-Control-Allow-Origin: * while the request carries cookies, the browser rejects the response. Ensure the exact origin and Access-Control-Allow-Credentials: true survive every hop together — see Credential Sharing & Security Boundaries.

Cache scoping. A shared cache that stores a CORS response without Vary: Origin can serve one origin’s grant to another. This is both a correctness bug and a boundary leak; keep Vary: Origin on every cached CORS response.

Proxy / CDN Interaction

When a preflight is terminated at the edge (see Proxy Bypass Strategies), the origin never emits CORS headers for that OPTIONS, so duplication is impossible there — but the edge now owns correctness entirely, including Vary: Origin and cache-key scoping. When the edge instead passes OPTIONS through, every intermediate layer must preserve the headers untouched. Mixing the two models — one layer terminating some preflights while another adds headers to the rest — is the most common way double-CORS bugs creep in after an infrastructure change.

DevTools + curl Verification Checklist

• Run the Step 1 direct-to-origin curl and confirm Access-Control-Allow-Origin is present and correct at the source
• Run the Step 2 through-the-edge curl and confirm the same headers arrive unchanged
• Diff the two responses — any added, dropped, or duplicated Access-Control-* header names the offending layer
• Force an error (curl a non-existent path) and confirm CORS headers still appear on the 4xx response — if not, an add_header always flag is missing
• Send an OPTIONS preflight and confirm the status is 204 (or 200), never 403 or 405
• Grep the edge response for a single Access-Control-Allow-Origin occurrence: curl -sI ... | grep -ci access-control-allow-origin should print 1
• Confirm Vary: Origin is present on any response a shared cache may store
• In Chrome DevTools → Network, select the failing request and read the Response Headers pane — compare against the curl output to rule out a caching or extension artefact
• Check the application access log — if it shows no OPTIONS entries, the preflight is being terminated (or blocked) upstream

Common Mistakes

FAQ