CORS errors, explained properly

First things first: your request probably worked

The thing almost every guide gets wrong, or at least buries: a CORS error does not mean your request failed to reach the server. In most cases the browser sent the request, the server processed it, returned a 200, and the browser then refused to hand the response to your JavaScript. Check your server logs while the console shows a CORS error. The request is right there.

That’s because CORS is not a firewall, it’s a read permission. Browsers enforce the same-origin policy, a rule that goes back to Netscape Navigator 2.0 in 1995, the same release that introduced JavaScript. Scripts on origin A don’t get to read responses from origin B. CORS (a W3C recommendation since January 2014, now folded into the WHATWG Fetch standard) is the opt-in mechanism that lets origin B say “this origin may read me” via response headers.

So the mental model that makes everything click: the server grants permission, the browser enforces it, and your frontend code is just the bystander that gets told no. Which explains the classic confusion, too: curl and Postman never show CORS errors because they aren’t browsers and enforce nothing.

What your exact message means

Chrome writes a different sentence for each cause, and the sentence is the diagnosis. Find yours:

Why you can’t catch it in JavaScript

Try to handle a CORS failure in code and you get remarkably little. fetch() rejects with a bare TypeError: Failed to fetch in Chrome, NetworkError when attempting to fetch a resource in Firefox. XHR reports status: 0. No status code, no headers, no hint that CORS was the reason. The useful message exists only in the devtools console.

Annoying, but deliberate. If JavaScript could inspect why a cross-origin request was blocked, it could probe your internal network: distinguish “host exists but blocked” from “host doesn’t exist”, map intranet services, that kind of thing. So the spec flattens every cross-origin failure into the same opaque network error. Your monitoring can’t tell CORS from a dropped connection either, which is worth knowing before you burn an afternoon on Sentry reports that just say “Failed to fetch”.

Practical consequence: debug CORS in the Network tab, not in your code. Look at the actual response headers of the blocked request (the browser did receive them) and compare against what the error message in the console says it wanted.

Preflight: the OPTIONS request you didn’t send

CORS distinguishes “simple” requests from everything else. Simple requests go straight out, like a form submission would have in 1998. Everything else gets a preflight: the browser first sends an OPTIONS request asking for permission, and only sends your real request if the answer satisfies it.

What makes a request non-simple is narrower than most people think:

The JSON row is the one that bites everyone. The simple list is exactly what an HTML form could already send before CORS existed, so it added no new attack surface. application/json wasn’t on that list, so the single most common API request shape (POST with a JSON body) is always preflighted. If OPTIONS requests die somewhere on the way to your app, you get the signature pattern: GETs work, JSON POSTs fail.

Two lesser-known preflight facts that solve real mysteries:

• Preflight results are barely cached. No Access-Control-Max-Age header means the result is cached for all of 5 seconds (the Fetch spec default). And you can’t cache generously either: Chromium caps the value at 7200 seconds (2 hours) no matter what you send, Firefox at 86400 (24 hours). If your API sees a steady stream of OPTIONS requests, that’s why.
• Preflights must not redirect. A 301 from http to https, or a redirect adding a trailing slash, is a spec-level CORS failure. The error message doesn’t say “redirect”, it says the usual CORS boilerplate, so people rarely suspect their own rewrite rules. Call the https URL with the exact final path and the problem evaporates.

Fixes that actually fix it

Every real fix is server-side. The server needs to answer with Access-Control-Allow-Origin matching the requesting page’s origin (scheme + host + port, so http://localhost:3000 and http://localhost:5173 are different origins). For preflighted requests, the OPTIONS response additionally needs Access-Control-Allow-Methods and Access-Control-Allow-Headers covering what the real request will do, and it has to come back with a 2xx.

In Express that’s the cors middleware, in Spring it’s @CrossOrigin or a global CorsRegistry, in Django it’s django-cors-headers, and every framework has its version. Use it instead of hand-rolling headers; the hand-rolled versions are where the subtle bugs live.

If you do hand-roll (or run nginx in front), three details matter more than the rest:

• nginx’s add_header ignores error responses. By default it applies to 2xx and 3xx only. Your 401s and 500s go out without CORS headers, the browser masks them as CORS errors, and you debug the wrong thing. The fix is one word: add_header Access-Control-Allow-Origin $origin always;.
• Echoing origins needs an allowlist. Reflecting whatever Origin arrives back into the header is equivalent to * but also works with credentials, which is the worst of both worlds. Compare against a fixed list, echo on match, omit the header otherwise.
• Send Vary: Origin when the header varies. Otherwise a cache (CDN or browser) stores the response with origin A baked in and serves it to origin B, producing CORS errors that depend on who visited first. These are miserable to reproduce.

Fixes that only look like fixes

The internet’s favourite CORS answers, ranked by how much time they waste:

• Adding Access-Control-Allow-Origin to the request. The all-time classic, still upvoted on Stack Overflow. It’s a response header. Setting it on your fetch call does nothing except sometimes making things worse, because a custom header can turn a simple request into a preflighted one.
• mode: 'no-cors'. Looks like an off switch, isn’t. It makes the response opaque: status 0, empty body, no headers readable. Your request “succeeds” and you can’t use the result for anything. It exists for fire-and-forget cases like beacons, not for reading data.
• Browser flags and unblock extensions. --disable-web-security disables the same-origin policy for every site in that profile, including your banking tab. As a quick local experiment to confirm a diagnosis, okay. As a fix you ship to teammates, no.
• Public CORS proxies. Routing your API traffic (with tokens) through a stranger’s server to avoid a header change on your own is a trade nobody should make. Run your own proxy if you must; it’s ten lines.

Cookies, credentials, and why * stops working

The rules change once requests carry credentials (cookies, or an Authorization header set by the browser). Then Access-Control-Allow-Origin: * is rejected outright; the server must echo the exact origin and add Access-Control-Allow-Credentials: true. And fetch doesn’t even send cookies cross-origin unless you pass credentials: 'include'. The number of “CORS is fine but the session is missing” bugs that come down to this default is large.

The restriction is the whole security story in one line: * plus credentials would mean any website can read any logged-in user’s data from your API. That’s the attack CORS exists to prevent. Related reading: our guide on SameSite cookie attributes, which is the other half of how browsers decide what cookies travel cross-site, and where to store JWTs, since the localStorage-vs-cookie decision changes which CORS rules you’re even playing by.

The CORS error that comes and goes

Intermittent CORS errors are almost never CORS. The usual suspects, in order of likelihood:

1. Only on failures. The API’s error path (500, 401, rate-limit 429) skips CORS headers, so only failing responses get blocked. The console blames CORS; the real bug is whatever caused the 500. See the nginx always trap above; API gateways and Lambda error responses do the same.
2. Only for some users. A cache without Vary: Origin is serving responses with someone else’s origin in the header.
3. Only the first request in a while. Preflight cache expired (remember: 5-second default), and the OPTIONS endpoint is flaky or rate-limited.
4. Only in one environment. Staging redirects http→https or strips trailing slashes, killing preflights; prod doesn’t. Or the allowlist simply doesn’t contain the staging origin.

Making it go away in development

For local development against a remote or containerised API, the clean solution is not CORS at all: make the requests same-origin by proxying them through your dev server. Vite’s server.proxy, webpack-dev-server’s proxy, or the proxy field in a CRA package.json all forward /api to the backend, and the browser only ever talks to one origin. No headers, no preflights, nothing to disable. In production the same trick is often right, too: serve frontend and API behind one domain and CORS stops being your problem entirely.

One more thing worth knowing for the local-network case: Chrome has been rolling out extra checks (Private Network Access) for public pages requesting private addresses like 192.168.x.x or localhost, with their own preflight headers on top of regular CORS. If a request from a deployed site to a device on your LAN fails in Chrome but works in Firefox, that’s the rabbit hole to check, not your header config.

CORS questions from the console