CORS Error Code Breakdown

Without a precise mapping between browser console output and the underlying HTTP exchange, CORS failures become a guessing game — you see a generic TypeError: Failed to fetch while the actual cause is hidden two layers deeper in a WAF rule or a misconfigured reverse proxy. This page maps every browser-reported error surface to its root cause and fix path.

This is a focused reference within Core CORS Mechanics & Same-Origin Policy Fundamentals. That parent covers the full browser enforcement model; this page goes deeper on the specific error signatures, their HTTP-level causes, and the diagnostic sequence to resolve each one.

Spec anchor: The WHATWG Fetch specification, §4.10 (CORS check algorithm), defines exactly when a browser blocks a cross-origin response. Every error listed below traces back to a branch in that algorithm — not to a browser quirk.

Error Surface Reference Table

The table below is the core diagnostic key. Match the console string and Network tab status to pinpoint the failure layer before touching any configuration.

How Browsers Separate CORS Errors from HTTP Errors

This distinction is the most common source of confusion. A CORS block is not an HTTP status code — it is a client-side enforcement step that runs after the HTTP response is received.

This matters for debugging: when you see TypeError: Failed to fetch, you cannot infer the HTTP status from the error itself. Open the Network tab, find the request, and read the response code directly.

Preflight 403 / 405 / 400 Failure Diagnostics

An OPTIONS preflight is issued automatically by the browser before any simple vs preflight request boundary is crossed: custom headers, non-simple methods (PUT, PATCH, DELETE), or Content-Type: application/json all trigger it. If the preflight fails, the actual request is never sent.

Spec rule

Per WHATWG Fetch §4.8.7, the preflight response must return HTTP status in the range 200–299. Any 4xx or 5xx aborts the CORS check immediately.

Why preflights fail

WAF / CDN blocking OPTIONS

Many web application firewalls block or drop OPTIONS requests by default. The browser receives a 403 from the WAF before the request reaches the origin server. The CORS middleware never runs.

# Test whether the WAF is the blocker — send OPTIONS directly with curl
curl -v -X OPTIONS \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type, Authorization" \
  https://api.example.com/resource

If you see < HTTP/2 403 and no Access-Control-Allow-* headers in the response, the WAF is intercepting before the application.

Framework routing returning 405

Express, Django, Rails, and most frameworks ignore OPTIONS by default unless a route is registered. Without an explicit handler, the router returns 405 Method Not Allowed.

// Express: register the OPTIONS handler BEFORE authentication middleware
const corsOrigins = ['https://app.example.com', 'https://admin.example.com'];

function isValidOrigin(origin) {
  return corsOrigins.includes(origin);
}

// This must appear before app.use(authMiddleware)
app.options('*', (req, res) => {
  const origin = req.headers.origin;
  if (!isValidOrigin(origin)) return res.sendStatus(403);
  res.set({
    'Access-Control-Allow-Origin': origin,
    'Access-Control-Allow-Methods': 'GET, POST, PUT, PATCH, DELETE',
    'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Request-ID',
    'Access-Control-Max-Age': '600',
    'Vary': 'Origin'
  });
  res.sendStatus(204);
});

Header mismatch returning 400

When the Access-Control-Request-Headers value in the preflight contains a header name that the server does not explicitly list in Access-Control-Allow-Headers, some servers return 400 Bad Request. This is not a browser block — the server itself is rejecting the OPTIONS request.

Preflight response requirements

Origin Mismatch and Validation Failures

The Access-Control-Allow-Origin header must be an exact byte-for-byte match with the Origin header sent by the browser. Browsers perform this comparison per WHATWG Fetch §3.1 (origin serialization): scheme + host + port, case-sensitive, no trailing slash.

Common mismatch patterns

Dynamic origin reflection is the correct pattern for multi-origin APIs: validate the incoming Origin header against an explicit allowlist, then echo the validated origin verbatim. See dynamic origin validation patterns for allowlist implementation in Nginx and Express.

# Nginx: dynamic reflection with a map block
map $http_origin $cors_origin {
  default               "";
  "https://app.example.com"   $http_origin;
  "https://admin.example.com" $http_origin;
}

server {
  location /api/ {
    if ($cors_origin) {
      add_header Access-Control-Allow-Origin $cors_origin always;
      add_header Vary Origin always;
    }
    # ... proxy_pass
  }
}

Null-origin and sandboxed iframes

Browsers send Origin: null from sandboxed <iframe> elements (those without allow-same-origin), local file:// URLs, and some data-URI contexts. Servers that reflect the Origin header will reflect null, then return Access-Control-Allow-Origin: null. This works mechanically but is a security risk — any sandboxed document on any site can send Origin: null. Do not allowlist null unless access to the resource is genuinely public.

Credential and Security Boundary Violations

When client code sets credentials: 'include' (Fetch API) or withCredentials = true (XHR), the browser enforces two additional rules beyond basic origin matching.

Rule 1: Access-Control-Allow-Origin must contain the exact requesting origin — never *.

Rule 2: The server must return Access-Control-Allow-Credentials: true.

Both rules must be satisfied simultaneously. Violating either produces the console error:

The value of the 'Access-Control-Allow-Origin' header in the response must not
be the wildcard '*' when the request's credentials mode is 'include'.

For the full credential isolation specification, see credential sharing and security boundaries.

Opaque responses and no-cors mode

Setting mode: 'no-cors' on a fetch request prevents the CORS preflight and suppresses the CORS error — but the trade-off is severe: you receive an opaque response. An opaque response has:

• Status code: always 0
• Headers: empty
• Body: unreadable

Opaque responses are useful only when the resource is loaded for a side effect (e.g., preloading a font, pinging a URL) and the content never needs to be read. Using no-cors to silence a CORS error in an API call is not a fix — the response will be empty.

Access-Control-Expose-Headers and header visibility

By default, JavaScript can only read six “safe” response headers from a cross-origin response: Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Last-Modified. Any custom header (X-Request-ID, X-Rate-Limit-Remaining, etc.) is invisible unless the server explicitly lists it:

Access-Control-Expose-Headers: X-Request-ID, X-Rate-Limit-Remaining

Without this header, response.headers.get('X-Request-ID') returns null — silently, with no console error.

SameSite cookie alignment

When cookies are involved in a credentialed cross-origin request, the cookie’s SameSite attribute must be None, and it must be marked Secure. A cookie set with SameSite=Lax or SameSite=Strict is not sent on cross-origin requests regardless of how CORS headers are configured.

Edge Cases and Infrastructure Interactions

Duplicate Access-Control-Allow-Origin headers

A common production failure: the application server emits Access-Control-Allow-Origin: https://app.example.com, and a CDN or reverse proxy also adds the header. The response arrives with two Access-Control-Allow-Origin values. Browsers reject this:

The 'Access-Control-Allow-Origin' header contains multiple values
'https://app.example.com, https://app.example.com', but only one is allowed.

Fix: configure the CDN to pass the header from the origin rather than add its own, or remove the CORS header from one layer. Set Vary: Origin to prevent the CDN from serving the wrong cached origin to different clients.

CDN cache poisoning without Vary: Origin

Omitting Vary: Origin from CORS responses allows CDNs to cache a response with one origin’s headers and serve it to a different origin’s request. The second client receives the wrong Access-Control-Allow-Origin value and sees a CORS error — intermittently, and only from cache. This is difficult to reproduce locally and is one of the most common production-only CORS failures.

Reverse proxy header stripping

Some reverse proxy configurations (Nginx, HAProxy, AWS ALB) strip certain headers. If CORS headers are added by the application server but stripped before the response reaches the client, the browser sees a response with no CORS headers.

Test with curl directly to the origin server (bypassing the proxy) and again through the proxy to identify the stripping layer.

Systematic Debugging Workflow

DevTools and curl verification checklist

• Open DevTools → Network tab. Filter by Fetch/XHR. Locate the failing request.
• Check the HTTP status code in the response. (failed) or status 0 means the browser blocked it; a real status (200, 403, etc.) means the server responded and the browser inspected headers.
• Expand the Response Headers panel. Confirm whether Access-Control-Allow-Origin is present.
• If the request has a preflight (OPTIONS), find it in the Network tab. Check its status code and response headers separately.
• Run the curl diagnostic to bypass the browser:

curl -v -X OPTIONS \
  -H "Origin: https://your-client.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type, Authorization" \
  https://your-api.example.com/endpoint

• Verify Access-Control-Allow-Origin in the curl response matches Origin exactly.
• Verify Access-Control-Allow-Methods includes the actual method you intend to use.
• Verify Access-Control-Allow-Headers includes all non-simple headers in your request.
• Check whether the header appears twice (duplicate injection).
• If using credentials, confirm Access-Control-Allow-Credentials: true is present and origin is not *.
• Temporarily bypass CDN/WAF and run curl again to test origin directly, ruling out header stripping.
• Check server-side logs for OPTIONS requests — confirm they reach the CORS middleware, not an auth layer.

Client-side error isolation wrapper

async function debugCorsRequest(url, options = {}) {
  try {
    const response = await fetch(url, { ...options, mode: 'cors' });
    if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    return response;
  } catch (err) {
    if (err instanceof TypeError && err.message.includes('Failed to fetch')) {
      // The browser blocked the response due to CORS policy.
      // The actual HTTP status is only visible in DevTools — it cannot be read from JS.
      console.error('[CORS] Request blocked by browser policy. Check DevTools Network tab for the HTTP status and response headers.');
      console.error('[CORS] Run: curl -v -X OPTIONS -H "Origin: <your-origin>" ' + url);
    }
    throw err;
  }
}

For a targeted walkthrough of debugging a missing Access-Control-Allow-Origin header, including step-by-step resolution for the most common server stacks, see the dedicated guide.

Common Mistakes

FAQ