Fixing CORS Errors: How CORS Actually Works — A Practitioner's Guide

Fixing CORS Errors: How CORS Actually Works — A Practitioner's Guide

There's a specific moment every web developer knows. The API works in Postman. It works in curl. The backend logs show a clean 200. And the browser console says:

Access to fetch at 'https://api.example.com/data' from origin 'https://app.example.com'
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present
on the requested resource.

The instinct is to treat this as an error to be silenced — find the magic header, sprinkle it somewhere, move on. That instinct is why CORS bugs come back every few months. The mechanism is actually small and coherent; it just protects something different from what most people assume. Fifteen minutes of mental model saves the fifth afternoon of whack-a-mole.

What CORS is actually for

Start from the threat. You're logged into your bank in one tab. In another tab, you open a shady website. That site's JavaScript quietly does:

const res = await fetch('https://yourbank.com/api/accounts');
const yourMoney = await res.json();  // ← this is the part that must not work

If the browser attached your bank cookies and let that script read the response, every website you visit could read your data from every other website you're logged into. The same-origin policy — a browser rule dating back to 1995 — forbids it: scripts may only read responses from their own origin.

Two consequences of that framing explain 90% of CORS confusion:

1. CORS is enforced by the browser, for the user's benefit. Your server is not being protected. curl, Postman, and other servers ignore CORS entirely — which is why "it works in Postman" is expected, not a clue that something's broken.
2. CORS is the opt-out from that restriction, not the restriction itself. Cross-Origin Resource Sharing is the server saying "these other origins may read my responses." No CORS headers means the default applies: nobody may.

So when the console says blocked by CORS policy, translate it as: "the server didn't say your site is allowed to read this." The fix lives on the server. Always.

What counts as a different origin

An origin is the exact triple of scheme + host + port. All of these are different origins from https://app.example.com:

Same-with-different-path, however, is the same origin — paths don't matter. When in doubt, decompose the URL and compare the three parts mechanically. The "works on localhost, breaks in production" classic is usually just this table: http://localhost:3000 was allowlisted, https://www.app.example.com wasn't.

The browser puts that triple on the wire in a header it sets itself and your JavaScript cannot touch:

Origin: https://app.example.com

Note what isn't there: no path, no query string, no trailing slash. That last one is the most common typo in a server allowlist — 'https://app.example.com/' matches nothing, because no browser has ever sent it. Run this in the DevTools console on the failing page and whatever it prints is what the server must allow, byte for byte:

new URL(window.location.href).origin;  // "https://app.example.com"

Simple requests vs. preflighted requests

The browser sorts every cross-origin request into one of two flows, and your own code decides which:

// simple — a form could have sent this, so it goes straight out
fetch('https://api.example.com/data');

// preflighted — JSON body, so an OPTIONS request happens first
fetch('https://api.example.com/data', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ ok: true }),
});

Simple requests are those a plain HTML form or <img> tag could have produced anyway: GET, HEAD, or POST with a Content-Type of application/x-www-form-urlencoded, multipart/form-data, or text/plain, and no custom headers. These are sent immediately — the server receives and processes them — and the browser only checks the response's Access-Control-Allow-Origin before deciding whether your script may read it. (Yes, that means CORS did not stop the request from executing. Let that sink in before relying on it for anything security-shaped.)

Everything else gets a preflight. Send JSON (Content-Type: application/json), use PUT/DELETE/PATCH, or attach an Authorization header, and the browser first sends its own request you never wrote:

OPTIONS /data HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: authorization, content-type

That's the browser asking permission. Read it as three questions: I'm this origin, I want to use this method, and I want to send these headers — may I? The server must answer with headers that cover the ask:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 86400
Vary: Origin

Only then does the real PUT go out, and only then does the handler you actually wrote run. If the preflight fails, your request never happened — which is why staring at server logs for the missing request is so maddening. Look for the OPTIONS line instead.

The whole timeline: fetch is called → the browser sees the request isn't simple → it sends OPTIONS → the server answers → the browser compares that answer to the ask → the real PUT goes out → the browser checks Access-Control-Allow-Origin again on the real response before handing it to your promise. Two checks, two places to get it wrong: a passing preflight says nothing about the real response, which needs its own header.

Access-Control-Max-Age: 86400 tells the browser to cache this permission for a day instead of preflighting every call. It's the cheapest CORS-related performance win there is; browsers cap it (Chrome at 2 hours, Firefox at 24), but even that eliminates most of the OPTIONS chatter.

One carve-out worth memorizing: the wildcard * is legal in Access-Control-Allow-Headers for non-credentialed requests, but by spec it does not cover Authorization, which must always be listed by name. That's why a config that "allows everything" still breaks the day you add JWT-based auth to the frontend.

The credentials rule, or: why * suddenly stopped working

By default, cross-origin requests carry no cookies. The moment you want session-cookie auth across origins, the frontend opts in:

fetch('https://api.example.com/me', { credentials: 'include' });

…and the rules tighten. For a credentialed request, the browser rejects the response unless:

• Access-Control-Allow-Credentials: true is present, and
• Access-Control-Allow-Origin names the exact origin — the wildcard * is forbidden, and so are wildcards in Allow-Headers and Allow-Methods.

This is the second-most-common CORS error in the wild, and the error message says it plainly: "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'."

The correct pattern is an allowlist check that echoes the origin back:

// Express — the manual version, so you can see exactly what's being set
const ALLOWED = new Set([
  'https://app.example.com',
  'https://staging.example.com',
]);

app.use((req, res, next) => {
  const origin = req.headers.origin;
  if (origin && ALLOWED.has(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);  // echo, don't wildcard
    res.setHeader('Access-Control-Allow-Credentials', 'true');
    res.vary('Origin');                                    // append, don't clobber
    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
    res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type');
    res.setHeader('Access-Control-Max-Age', '7200');
  }
  if (req.method === 'OPTIONS') return res.sendStatus(204); // before auth middleware!
  next();
});

Two details in there earn their keep:

• Vary: Origin, set with res.vary() — without the header, a CDN can cache the response with origin A's value baked in and serve it to origin B, producing CORS failures that appear and disappear "randomly." Use res.vary('Origin') rather than res.setHeader('Vary', 'Origin'): setHeader replaces the whole field and silently deletes the Vary: Accept-Encoding your compression middleware set, breaking gzip caching. res.vary() appends.
• OPTIONS handled before auth — preflights arrive with no cookies and no Authorization header, by spec. If your auth middleware runs first, it 401s the anonymous preflight and the browser reports it as CORS. Middleware order is the fix, not more headers.

Server recipes: the cors package and nginx

Nobody hand-writes that middleware twice. For Express the cors package is the standard answer — and worth seeing fully specified, not as the app.use(cors()) one-liner that ships wildcards to production:

// npm install cors
const cors = require('cors');

const ALLOWED = ['https://app.example.com', 'https://staging.example.com'];

app.use(cors({
  origin(origin, callback) {
    // `origin` is undefined for same-origin requests and for non-browser
    // clients (curl, server-to-server) — those aren't CORS requests at all.
    if (!origin || ALLOWED.includes(origin)) return callback(null, true);
    callback(null, false);   // just omit the header; don't throw
  },
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Authorization', 'Content-Type'],
  exposedHeaders: ['X-Request-Id'],
  maxAge: 7200,
}));

// everything below this line is now preflight-safe
app.use(requireAuth);
app.use('/api', apiRoutes);

The package handles two things people re-implement badly: it adds Vary: Origin whenever origin is anything other than *, and it answers preflights itself with a 204 rather than passing them down the stack. Two to watch: app.use(cors(...)) must sit above your auth middleware, and calling callback(new Error(...)) for a disallowed origin — which half the tutorials do — sends it to your error handler, which returns a 500 without CORS headers, so the browser reports "no Access-Control-Allow-Origin" instead. Passing false is honest: the header is simply absent.

The nginx flavor of the same idea, for when the API sits behind a reverse proxy:

location /api/ {
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin $http_origin always;
        add_header Access-Control-Allow-Credentials true always;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE" always;
        add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
        add_header Access-Control-Max-Age 7200 always;
        add_header Vary Origin always;
        return 204;
    }

    add_header Access-Control-Allow-Origin $http_origin always;
    add_header Access-Control-Allow-Credentials true always;
    add_header Vary Origin always;

    proxy_pass http://backend;
}

The Vary Origin in the OPTIONS branch is not decoration: preflight responses are cacheable too — that's what Access-Control-Max-Age is for — and without it a shared cache will reuse origin A's preflight answer for origin B.

Three nginx-specific traps come with this. The $http_origin echo allows every origin with credentials: fine behind a VPN, reckless in public, so pair it with a map block resolving an allowlist to either the origin or an empty string. The always parameter matters more than it looks — without it nginx skips add_header on error responses, so 4xx and 5xx replies arrive with no CORS headers and the frontend sees a CORS error stacked on top of the real one. And add_header doesn't merge across levels: adding one inside a location drops every header inherited from the enclosing server block, which is how a CORS fix silently disables your HSTS and CSP. The Apache and nginx hardening guide covers what you'll need to repeat there.

Headers your script can't read: Access-Control-Expose-Headers

Here's a failure that doesn't look like CORS at all, because there's no console error. Your API returns a request ID for support tickets, DevTools shows it plainly in the Response Headers, and this returns null:

const res = await fetch('https://api.example.com/data');

res.headers.get('content-type');   // "application/json"  ✅ safelisted
res.headers.get('x-request-id');   // null                ❌ not exposed

Reading response headers cross-origin has its own gate. By default a script can only see the CORS-safelisted response headers: Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Last-Modified, and Pragma. Everything else — your rate-limit counters, pagination totals, request IDs, Location on a 201 — is invisible to JavaScript until the server names it:

Access-Control-Expose-Headers: X-Request-Id, X-RateLimit-Remaining, X-Total-Count

In the cors package that's the exposedHeaders array from the recipe above; in raw Express it's one more res.setHeader. The wildcard Access-Control-Expose-Headers: * exists and exposes everything, but — same rule as always — it's ignored for credentialed requests, where you must list each header by name. Worth deciding when you design the API rather than after: if pagination metadata lives in headers and the browser is a first-class client, exposing them is part of the contract.

The five errors, decoded

Nearly every CORS failure is one of these. The console message tells you which — read it before changing anything.

1. "No 'Access-Control-Allow-Origin' header is present." The server sent nothing: either CORS isn't configured, or something between browser and app (CDN, proxy, error page) stripped it. Check the actual response headers, not your config — our CORS header checker shows what an external client really receives, preflight included.

2. "…must not be the wildcard '*' when the request's credentials mode is 'include'." The wildcard/credentials clash from the previous section. Echo the exact origin.

3. "Response to preflight request doesn't pass access control check." The OPTIONS request failed — 401 from auth middleware, 404 because no OPTIONS route exists, or a redirect (a http→https or trailing-slash one is enough; preflights don't follow them). Chrome usually appends the reason, and "It does not have HTTP ok status" means the OPTIONS response wasn't a 2xx.

4. "Request header field x-custom-header is not allowed by Access-Control-Allow-Headers." Your Allow-Headers list doesn't cover a header the app sends. Authorization is the perennial omission — teams add JWT auth, forget the preflight contract, and the * wildcard doesn't cover it. Its silent mirror image is the previous section: a header you read needs Access-Control-Expose-Headers, or headers.get() hands you null while DevTools shows it sitting right there.

5. It works everywhere except production, intermittently. Cache poisoning from a missing Vary: Origin, or a CDN/gateway with its own CORS opinions overriding yours — the tell for that one is Chrome's "contains multiple values … but only one is allowed", two layers both adding the header, refused even when the values agree. Diagnose from outside: compare responses via the header checker, or rebuild the exact preflight with our curl command generator so you're testing what the browser tested.

Debugging a CORS error: the method

The mistake is to start editing server config straight from the error message. Ten minutes of looking — in this order — tells you which of the five it is, and whether the problem is even in your application at all.

Step 1 — Read the whole console message

Open DevTools with F12 (Cmd+Option+J on a Mac) and go to the Console tab. Read past the words "blocked by CORS policy" — everything useful is after the colon:

Access to fetch at 'https://api.example.com/data' from origin 'https://app.example.com'
has been blocked by CORS policy: Response to preflight request doesn't pass access
control check: It does not have HTTP ok status.

That's error 3, and it already tells you the OPTIONS response wasn't a 2xx — look at the preflight, not at the PUT. If the message is truncated, Chrome files the same failure in the Issues tab (the ⚠ icon beside Console) with a plain-English reason.

Step 2 — Find the OPTIONS request in the Network tab

Switch to the Network tab, click the All filter, and reload. The filter matters: Chrome types preflights as preflight, not xhr, so the popular Fetch/XHR filter hides the exact row you need. Then look for:

• Two rows for the same URL, the first with method OPTIONS — that confirms the request was preflighted.
• The Status column. A red CORS error on the OPTIONS row means the browser stopped there and your real request was never sent; a 401, 301, or 404 names the culprit outright.
• Click the failing row → Headers pane → Response Headers. That's ground truth: what the server actually sent after every proxy in the path had a turn. Your config is a hypothesis; this is evidence.

No OPTIONS row at all means the request was simple (GET/HEAD/POST with a safelisted Content-Type), the server really did run it, and the missing Access-Control-Allow-Origin is on the real response.

Step 3 — Reproduce the preflight with curl

Now leave the browser. This command sends exactly what the browser sent, with nothing else in the way:

curl -i -X OPTIONS 'https://api.example.com/data' \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: PUT' \
  -H 'Access-Control-Request-Headers: authorization, content-type'

What the flags do: -i prints the response headers along with the body (without it you'd see nothing at all, because a preflight has no body), -X OPTIONS sets the method, and each -H adds one request header. The three headers aren't decoration — Origin is what makes this a CORS request at all, and a server that keys off Access-Control-Request-Method answers differently without it.

A healthy server answers like this:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 7200
Vary: Origin

Four things to check there, in order: the status is 2xx (204 or 200); Access-Control-Allow-Origin is your origin exactly (or * if you're not using credentials); Access-Control-Allow-Methods contains the method you asked for; and Access-Control-Allow-Headers contains every header you asked for. Miss one and the browser blocks — silently, as far as your server logs are concerned. Anything else maps to a cause:

A passing preflight only unlocks the real request, so test that too — -d sends a body, and the grep trims the output to just the CORS headers:

curl -i -X PUT 'https://api.example.com/data' \
  -H 'Origin: https://app.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"name":"test"}' | grep -i '^access-control'

If that prints nothing while the OPTIONS check printed a full set, you've found the classic split-brain config: preflights answered by middleware that returns early, real responses served by a route that never got the headers.

Step 4 — Compare the origins, character by character

If the headers are present but the browser still complains, the strings don't match. Print the failing page's origin with the new URL(window.location.href).origin snippet from earlier, then compare it to your allowlist entry one field at a time: scheme, host, port. The four that catch people, roughly by frequency: a trailing slash in the config, www versus the apex domain, http versus https (a staging box on plain HTTP does this), and a port that changed when you switched dev servers — Vite's 5173 versus CRA's 3000. For a long URL, the URL parser splits it into fields so you're diffing parts rather than squinting at a string.

While you're here, re-run the Step 3 command with -H 'Origin: https://evil.example'. If the server echoes that back, your allowlist isn't checking anything — and with Allow-Credentials: true, any site on the internet can read authenticated responses through your users' browsers.

Step 5 — Verify from outside your network

This is the step people skip, and it's the one that catches production-only failures. Run the same curl against the deployed URL, not localhost, ideally from a machine that isn't yours — a VPS, a CI job, or an external checker. Our CORS header checker issues the preflight from outside your network and shows what a real browser receives, CDN edits included. If the external and local results disagree, something in the middle is rewriting; bypass the CDN and ask the origin server directly:

curl -i -X OPTIONS 'https://api.example.com/data' \
  --resolve api.example.com:443:203.0.113.10 \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: PUT'

--resolve host:port:ip forces curl to connect to that IP while still sending the real hostname and doing normal TLS, so you're testing the origin server with the CDN out of the path. Headers that show up here but not through the public URL mean the CDN is stripping them. Headers that are correct in both mean you're done.

When you don't own the server: dev proxies and backend proxies

Everything so far assumes you can change the server. Sometimes you can't — it's Stripe, it's a partner's API, or it's your own backend but you're three sprints from being allowed near it. Two honest answers exist, and both work by making the request stop being cross-origin.

In development, proxy through your dev server. Every modern dev server can forward a path prefix to another host, so the browser only ever talks to localhost and CORS never enters the picture. Vite:

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'https://api.example.com',
        changeOrigin: true,                          // rewrite the Host header to the target
        rewrite: (path) => path.replace(/^\/api/, ''),  // /api/data → /data
      },
    },
  },
});

Then call fetch('/api/data') instead of the absolute URL. The browser sees a same-origin request to http://localhost:5173/api/data; Vite's Node process — not a browser, so not bound by CORS — fetches the real URL and pipes the response back. Create React App does the same with one line in package.json:

{
  "proxy": "https://api.example.com"
}

CRA only proxies requests the dev server can't serve itself, and only in development — which is the catch for all of these. Production builds have no dev server, so a dev proxy is a local convenience, never a deployment strategy. Next.js rewrites() carries the same caveat plus one more: it doesn't exist under output: 'export', because a static export has no server to do the rewriting.

One related gotcha while you're pointed at localhost: Chromium has been phasing in Private Network Access checks, where a page on a public origin calling localhost or a private IP gets an extra preflight carrying Access-Control-Request-Private-Network: true, which the local server must answer with Access-Control-Allow-Private-Network: true. If a deployed staging site suddenly can't reach a developer's machine, that's the mechanism.

In production, proxy through your own backend. Same trick, permanent version: the browser calls your origin, and your server makes the third-party call, where CORS simply doesn't apply because there's no browser involved.

// Express — a minimal backend-for-frontend endpoint
app.get('/api/weather', async (req, res) => {
  const upstream = await fetch(
    `https://api.thirdparty.com/v1/weather?city=${encodeURIComponent(req.query.city)}`,
    { headers: { Authorization: `Bearer ${process.env.THIRDPARTY_KEY}` } },
  );
  res.status(upstream.status).json(await upstream.json());
});

The frontend calls /api/weather?city=Vienna — same origin, no preflight, no CORS headers needed anywhere. Note what else that bought you: the API key lives in process.env instead of in a bundle any visitor can read, and you can cache and rate-limit the upstream call. That's the backend-for-frontend pattern, usually the right architecture rather than a workaround; the API architecture guide covers where to draw that line. Honest cost: one more hop of latency and a service you now have to keep running.

What CORS is not

Worth stating plainly, because both misconceptions cause real incidents:

CORS does not protect your API. Anyone can call your endpoints with curl or a script — no browser, no CORS. Locking Access-Control-Allow-Origin to your domain does not make endpoints private; authentication and rate limiting do. We've seen "internal" APIs left unauthenticated because "CORS blocks other sites" — it blocks other sites' browser JavaScript from reading responses, nothing more. Remember also that simple requests execute server-side before the browser blocks anything: a cross-origin POST that transfers money will transfer the money and then hide the response.

CORS is not your CSRF defense. CSRF is an attacker triggering a state-changing request with the victim's cookies — and simple requests (form posts) sail through without any preflight. SameSite cookies and CSRF tokens address that; CORS configuration doesn't. If you're testing how your endpoints behave when browsers hit them cross-origin, the API tester and webhook tester make quick work of it.

And the fix is never "disable CORS." Browser flags and unblock-CORS extensions turn the protection off for every site in that browser — fine for five minutes of local debugging, dangerous as a habit, and useless for your users, who won't have the extension. Public "CORS proxy" services are worse: every request through them, tokens included, is readable by whoever runs the proxy. Use one of the two proxies from the previous section instead.

The CORS gotcha checklist

The failures in this article, compressed for future greps:

1. Trailing slash in the allowlist entry — https://app.example.com/ never matches; the Origin header has no path.
2. Wildcard with credentials — * is rejected outright for credentialed requests; echo the exact origin.
3. Auth middleware before CORS middleware — the anonymous preflight gets a 401, reported as a CORS error.
4. A redirect on the preflight — http→https or trailing-slash; preflights don't follow redirects.
5. Missing Vary: Origin — a shared cache serves origin A's header to origin B. Production-only, intermittent.
6. CORS headers on 2xx but not on errors — nginx add_header without always, or an error handler above the CORS middleware; the real 500 goes invisible.
7. Authorization missing from Allow-Headers — the * wildcard does not cover it, by spec.
8. Header visible in DevTools but null in JavaScript — it needs Access-Control-Expose-Headers.
9. Two Access-Control-Allow-Origin headers — app and proxy both adding it; browsers reject duplicates even when the values match.
10. add_header inside an nginx location — drops every header inherited from the server block, HSTS and CSP included.
11. Reflecting Origin unconditionally with credentials on — that's not an allowlist, that's an open door.
12. Treating CORS as a security control — it protects users' browser sessions, not your API, and it is not CSRF defense.

The short version

The browser forbids your script from reading another origin's responses unless that origin's server explicitly opts in, so every CORS error is one sentence: the server didn't say your site is allowed to read this. Preflights are the browser asking first when the request is unusual — anything beyond a plain form post — and they're a separate response that needs its own headers. Credentials tighten every rule: exact origin, no wildcards, Vary: Origin, and CORS middleware mounted above your auth. When it breaks, don't reason from your config; read the OPTIONS row in the Network tab, then reproduce it with curl -i -X OPTIONS and see what the wire actually carries. Then confirm the same thing from outside your network with the CORS header checker, because production proxies have opinions your framework knows nothing about — and if you'd rather not hand-assemble the preflight, the curl command generator builds it for you.