Decoding Browser CORS Error Messages

A CORS failure surfaces to a developer as a single red line in the browser console — but that line is the last step of a multi-stage algorithm, and its wording is chosen by the browser vendor, not the specification. Chrome, Firefox, and Safari describe the same underlying failure with three different sentences, and each embeds a short reason phrase that is the only reliable signal of what actually broke. Reading that phrase correctly is the difference between fixing a missing header in five minutes and rewriting a working server config for an hour.

This page is part of Cross-Origin Debugging & Error Diagnosis, which covers the end-to-end workflow of reproducing, inspecting, and resolving cross-origin failures. Here the focus is narrow and practical: a decoder that maps each exact console string to the WHATWG Fetch algorithm step it represents, the network layer where the fault lives, and the concrete remediation.

Why the Wording Matters More Than the Sentence

The WHATWG Fetch Standard defines a single “CORS check” algorithm and a single “CORS-preflight fetch” algorithm. When either fails, the spec returns a network error — an opaque failure with no readable status, headers, or body. Browsers are free to render that network error however they like in the console. The result is that the sentence structure varies by vendor, but each vendor appends a machine-generated reason phrase derived from the exact failing branch:

• Chrome: ... has been blocked by CORS policy: <reason>
• Firefox: Cross-Origin Request Blocked: ... (Reason: <reason>)
• Safari: a terse Origin ... is not allowed by Access-Control-Allow-Origin or Preflight response is not successful line in the console, with fuller detail in the Web Inspector Network tab.

The reason phrase is the payload. Two failures with identical Chrome sentences but different reason clauses have completely different fixes; two failures with different sentences (one Chrome, one Firefox) but equivalent reason clauses have the same fix. Decode by reason, never by prose.

Spec Anchor: Where Each Error Is Raised

Two algorithm locations produce nearly every CORS console error:

1. The CORS check (WHATWG Fetch §4.9). After a response is received, the browser compares the response’s Access-Control-Allow-Origin value against the request’s Origin. Absence, mismatch, or a wildcard used with credentials all fail this check.
2. The CORS-preflight fetch (WHATWG Fetch §4.8). Before a non-simple request, the browser sends an OPTIONS request and validates the response’s Access-Control-Allow-Methods and Access-Control-Allow-Headers. A failure here blocks the request before the real method is ever sent.

A third, distinct class is the failed fetch — the response never arrived in a usable form (TLS handshake failure, connection refused, mixed content, or the server never answered OPTIONS). Firefox names this precisely; Chrome and Safari fold it into a more generic Failed to fetch or Load failed. The CORS Error Code Breakdown covers the underlying status-to-cause mapping in more depth; this page is about the literal strings each browser prints.

Reference Table: Error String → Spec Rule → Fix

Each row below is keyed on the reason phrase (the part that varies with the actual fault), not the surrounding sentence. Header names are exact.

Browser-by-Browser Wording Differences

The same three faults print differently in each engine. The table below shows the verbatim leading sentence so you can identify the engine from a pasted log.

Two practical consequences follow. First, Firefox’s Status code: (null) is a strong signal that no HTTP response reached the browser — it is not a header problem. Second, Chrome throws Failed to fetch to JavaScript with no console detail for transport failures, so when a fetch() rejects with TypeError: Failed to fetch and the console is otherwise silent, treat it like Firefox’s CORS request did not succeed and check the transport, not the headers.

Mapping an Error String to Its Root-Cause Layer

Every CORS console string resolves to one of three layers. The diagram routes a pasted error to the layer that owns the fix.

Figure — one of three layers owns every CORS console error; the reason phrase tells you which.

Step-by-Step: Decode Any CORS Error

Step 1 — Capture the exact string, including the reason clause

Copy the whole console line, not a paraphrase. In Firefox the decisive token is inside the parentheses (Reason: ...); in Chrome it is the clause after blocked by CORS policy:. Preserve Status code: (null) if present — it is diagnostic.

Step 2 — Classify the layer with one question

Ask: did a real HTTP response arrive? If the message says Status code: (null), Failed to fetch, or Load failed with no reason clause, no usable response arrived — the fault is transport, and no header change will help. Otherwise a response arrived and the reason clause names the failing check.

Step 3 — Reproduce with curl to see the unfiltered response

curl is not bound by the same-origin policy, so it shows exactly what the server (and any proxy) returns:

curl -sS -D - -o /dev/null \
  -H "Origin: https://app.example.com" \
  https://api.example.com/v1/data

For a suspected preflight failure, send the OPTIONS request the browser would send:

curl -sS -D - -o /dev/null -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/v1/data

Step 4 — Compare curl output to the browser verdict

If curl shows the correct Access-Control-Allow-Origin but the browser reports it missing, a layer between the browser and origin is stripping or duplicating it — inspect each hop. If curl also lacks the header, the origin never emitted it and the fix is server-side.

Step 5 — Apply the row’s fix and re-verify

Use the reference table row that matches your reason phrase. After the change, re-run the curl command and reload with DevTools open; the console line must disappear entirely, not merely change wording.

Edge Cases That Disguise the Real Cause

Opaque redirects. A 3xx redirect on a CORS request produces a follow-up request whose failure is reported against the final URL, not the one your code called. The console origin may not match your fetch() argument. Check the Network panel for an intermediate 302.

null origin. Sandboxed iframes, data: URLs, and some file-protocol contexts send Origin: null. A server allowlist that does not include the literal string null will fail the CORS check even though the page “looks” same-site. Do not reflect null blindly — it grants access to every sandboxed context.

Cached preflight masking a fix. After you correct an OPTIONS response, the browser may still use a preflight cached under Access-Control-Max-Age. A stale cache makes a fixed server look broken. See cache duration tuning and Max-Age; to force a fresh preflight, restart the browser or reduce Access-Control-Max-Age.

Duplicate headers from a proxy. If both the origin and a reverse proxy add Access-Control-Allow-Origin, the browser sees https://a.example, https://a.example and rejects it as multi-valued — even though each layer is individually correct. This is a proxy-layer fault, covered under header deduplication techniques.

DevTools + curl Verification Checklist

• Copy the full console line including the Reason: clause (Firefox) or the phrase after blocked by CORS policy: (Chrome)
• Confirm whether the message carries Status code: (null) or Failed to fetch — if so, treat it as a transport failure, not a header problem
• In DevTools Network, enable Preserve log and locate both the OPTIONS and the actual request rows
• Inspect the actual response’s Response Headers for exactly one Access-Control-Allow-Origin value
• Run curl -sS -D - -o /dev/null -H "Origin: https://app.example.com" <URL> and compare its headers to the Network panel
• For preflight failures, run the curl -X OPTIONS reproduction and confirm Access-Control-Allow-Methods and Access-Control-Allow-Headers cover the real request
• Check for a 302/307 redirect row that changes the effective origin
• After fixing, reload with cache disabled and confirm the console line is gone, not merely reworded

Common Mistakes

FAQ