CORS errors decoded: every message mapped to its cause

Your app on https://staging.example.com calls your API on https://api-staging.example.com. It works in Postman. It works with curl. In the browser you get a paragraph of red text about a policy you did not write, and TypeError: Failed to fetch.

The message is long, but it is not vague. It names the exact header that is missing or wrong. Once you know how to read it, most CORS problems are a five-minute fix on the server.

Short version

• CORS is a browser rule. It only affects browsers, which is why curl and Postman never see it.
• The fix is almost always a response header on the server, not a change in your frontend code.
• The message tells you which header is wrong. Read past the first line.
• Some requests trigger a preflight — an extra OPTIONS request the browser sends first to ask permission.
• Credentials mode changes the rules: wildcards stop working and an extra header becomes required.
• A failed CORS request is often a 500 or a 404 in disguise. Check the Network tab before blaming CORS.

---

What CORS is, in one paragraph

By default a browser will not let JavaScript on one origin read a response from a different origin. An origin is the combination of scheme, host, and port — so https://example.com and https://api.example.com are different origins, and so are http://localhost:3000 and http://localhost:8080.

This rule is called the same-origin policy. Cross-Origin Resource Sharing, or CORS, is the opt-out: the server sends headers that say "this origin is allowed to read my response." No headers means no permission, and the browser hides the response from your code.

Two things follow, and both surprise people:

1. The request usually still reached the server. The browser blocked the reading of the response, not the sending. A POST /api/orders that "failed with CORS" may well have created the order.
2. You cannot fix it from the frontend. No fetch option makes the browser ignore the rule. The header has to come from the server, or from a proxy in front of it.

---

Preflight, explained simply

For simple requests the browser just sends them and checks the response headers afterwards. For anything else it asks first.

That advance question is the preflight: an OPTIONS request to the same URL, carrying two headers:

OPTIONS /v2/orders HTTP/1.1
Origin: https://staging.example.com
Access-Control-Request-Method: PATCH
Access-Control-Request-Headers: authorization,content-type

The server must answer with 200 or 204 and permission headers:

Access-Control-Allow-Origin: https://staging.example.com
Access-Control-Allow-Methods: GET,POST,PATCH,DELETE
Access-Control-Allow-Headers: authorization,content-type
Access-Control-Max-Age: 600

Only then does the browser send the real request.

A request is "simple" and skips preflight only if it uses GET, HEAD, or POST, sends no unusual headers, and its Content-Type is application/x-www-form-urlencoded, multipart/form-data, or text/plain.

In practice this means: Content-Type: application/json triggers a preflight, and so does an Authorization header. Almost every real API call is preflighted.

Access-Control-Max-Age tells the browser how long it may reuse the answer. Setting it to 600 removes the extra round trip for ten minutes and is a cheap performance win.

---

The messages, mapped

Chrome and Edge use the phrase "has been blocked by CORS policy" and then explain. Firefox uses "Cross-Origin Request Blocked" and gives a Reason:. Safari is the least specific. The table below uses Chrome wording.

---

The three mistakes behind most CORS tickets

1. It is not a CORS problem

Failed to fetch with a CORS message often hides something simpler. Open the Network tab and look at the failing row.

• If the status is 500, the server crashed before the CORS middleware ran. Fix the crash and the CORS message disappears.
• If the status is 404, the URL is wrong.
• If the row says (failed) net::ERR_CONNECTION_REFUSED, nothing is listening on that port.

Bad: "CORS is broken on staging."

Good: "POST https://api-staging.example.com/v2/orders returns 500 with no CORS headers. The 500 is the real bug; CORS is the symptom."

2. The preflight is authenticated

Many frameworks put authentication middleware in front of every route. The browser sends OPTIONS without cookies or an Authorization header, so the middleware returns 401, and the browser reports a failed preflight.

The rule: OPTIONS requests must be answered before any auth check.

3. Wildcard plus credentials

This combination never works:

Access-Control-Allow-Origin: *

fetch(url, { credentials: 'include' });

When credentials are involved the server must name the origin exactly. The usual pattern is to keep a list of allowed origins, compare the incoming Origin header against it, echo the match back, and set Vary: Origin so caches do not serve one origin's response to another.

---

A checklist for debugging a CORS failure

1. Open DevTools, go to Network, and tick Preserve log.
2. Reproduce. Find the failing request. If there are two rows for the same URL, the first is the preflight.
3. Click the preflight row. Confirm it returned 200 or 204. If not, that is your bug.
4. Read the Response Headers of the preflight. Compare each allow header against what the browser asked for in Access-Control-Request-Method and Access-Control-Request-Headers.
5. Check the origin string character by character. https://staging.example.com and https://staging.example.com/ are not the same value.
6. Retry the same URL with curl and an Origin header to see the raw response:

   curl -i -X OPTIONS https://api-staging.example.com/v2/orders \
     -H "Origin: https://staging.example.com" \
     -H "Access-Control-Request-Method: POST"
   

7. If curl shows the headers but the browser does not, something between them — a CDN, a load balancer, a cache — is stripping or overwriting them.

For a bug report, include the request URL, the preflight response headers, the exact console message, and the origin you were on. Tools such as Crosscheck capture the console output and network requests with the report, which saves the back-and-forth of asking a tester to re-run the steps with DevTools open.

---

What not to do

• Do not disable web security in your browser to make the message go away. It hides the problem and it is not how your users run your app.
• Do not add a public CORS proxy to production traffic. You are routing your users' tokens through a stranger's server.
• Do not set Access-Control-Allow-Origin: * on an authenticated API. It does not even work with credentials, and on a public endpoint it removes a real protection.
• Do not "fix" it in the frontend. mode: 'no-cors' does not bypass anything. It gives you an opaque response your code cannot read, which looks like success and is not.

The legitimate frontend-side workaround is a development proxy: your dev server forwards /api to the real API, so the browser sees one origin. That is fine locally, but it means CORS is untested until staging, so configure the real headers early.

---

Frequently asked questions

Why does the request work in Postman but not in the browser? CORS is enforced by browsers only. Postman and curl have no origin and no same-origin policy, so they never see the restriction.

Did my POST actually reach the server? If a preflight failed, no. If the real request was sent and only the response was blocked, yes — the server processed it. Check your server logs before retrying.

Why do I see two requests for the same URL? The first is the preflight OPTIONS, the second is the real request. Seeing only the OPTIONS means the preflight failed.

Can I cache the preflight? Yes. Set Access-Control-Max-Age to a value such as 600 seconds. Browsers cap it, but it still removes most repeat round trips.

Does CORS protect my API? Not on its own. It stops other websites from reading responses in a user's browser. Anything can still call your API directly, so keep your authentication and authorization checks.