CORS error: the server never said yes

The browser is not blocking your code

A browser will happily send your request to another origin. What it will not do is hand the response to your JavaScript. That is the default every page starts from, and it is the whole of the same origin policy: script running on one origin may read data from that origin and from nowhere else. An origin is a scheme, a host and a port together, so http and https are different origins, and so are two ports on the same machine.

CORS is how a server opts out of that default. The response carries headers naming which origins are allowed to read it, and the browser enforces whatever the server said. The permission is a whitelist, and it belongs to the server. That is the part most people have backwards: there is nothing to configure on your side, because your side is not the one granting anything.

It is worth being precise about what is withheld, because it changes where you look. For a request simple enough to skip the preflight, the call is delivered, the server runs it, and only the reading of the response is refused. The row really was inserted. CORS is not protecting that server from your page. It is protecting a signed in user from a page that has no business reading their data.

What the message is actually telling you

Three messages cover almost every case, and they point at three different servers doing three different things. Reading which one you have is most of the diagnosis.

// the server sent no CORS headers at all
Access to fetch at 'https://api.example.com/orders' from origin
'http://localhost:3000' has been blocked by CORS policy: No
'Access-Control-Allow-Origin' header is present on the requested resource.

// the server allows someone, just not you
... blocked by CORS policy: The 'Access-Control-Allow-Origin' header has a
value 'https://app.example.com' that is not equal to the supplied origin.

// the OPTIONS failed, so the request you wrote was never sent
... blocked by CORS policy: Response to preflight request doesn't pass
access control check.

The first means the server has no CORS configuration at all, or none that applies to this route. The second means it does have one and your origin is not on the list, which is the one that catches people moving between localhost ports. The third is not about your request at all, it is about the OPTIONS the browser sent ahead of it, and it is the reason the request you were debugging never appears in the server log.

One thing none of these give you is a status code. A blocked response is opaque, so the fetch rejects with a bare TypeError and your error handler cannot tell a CORS refusal from a dead network. That opacity is what makes this failure so slow to trace, and it is deliberate: telling the page why it was refused would leak the thing being protected.

The request that gets sent twice

Some cross origin requests are sent straight away. Others are announced first, with an OPTIONS request asking whether the real one would be allowed. That announcement is the preflight, and the browser decides on its own whether to send it.

OPTIONS /orders HTTP/1.1
Origin: http://localhost:3000
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://localhost:3000
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: content-type
Access-Control-Max-Age: 600

A request skips the preflight only when the method is GET, HEAD or POST, every header on it is CORS safelisted, and the content type is one of three values: a form encoding, multipart form data, or text/plain. Anything else and the browser asks first.

// no preflight: with no Content-Type set, the browser sends text/plain,
// which is on the safelist
fetch(url, { method: "POST", body: data })

// preflight: application/json is not on the safelist, so this same call
// becomes two round trips
fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(data),
})

This catches almost everyone, because sending JSON is the most ordinary thing an application does and it is enough on its own to turn one request into two. An Authorization header or any custom header starting with X does the same. When the preflight is what fails, the fix belongs on the OPTIONS response rather than on the one you were watching, and Access-Control-Max-Age is what stops the browser asking again on every call.

The wildcard stops working the moment credentials appear

An open server answers with Access-Control-Allow-Origin set to an asterisk, which means any origin may read this. That works right up until the request starts carrying cookies or an Authorization header, and then no browser will accept it. A credentialed request requires the server to name the calling origin outright and to send Access-Control-Allow-Credentials alongside it.

The rule exists so that a public resource cannot be turned into a private one by accident. The asterisk is a statement that the response holds nothing worth protecting, and a response assembled from the cookies a browser attached is not that. The consequence is that the moment you add authentication to a call that already worked, the CORS setup that was fine yesterday has to become an explicit list, and the error you get says nothing about credentials at all.

The header arrives and JavaScript still reads null

This one does not produce an error, which is why it costs an afternoon. A cross origin response only exposes a small safelist of headers to script: cache-control, content-language, content-length, content-type, expires, last-modified and pragma. Everything else is present on the wire, visible in the network tab, and unreadable from code.

// the server sends it
X-Total-Count: 148

// JavaScript still reads nothing
res.headers.get("X-Total-Count")   // null

// until the server also sends this
Access-Control-Expose-Headers: X-Total-Count

So a pagination count, an ETag or a Location you set yourself is invisible until the server names it in Access-Control-Expose-Headers. The symptom looks exactly like a server that forgot to send the header, which sends you off to check the wrong side of the connection. Open the network tab, find the header sitting in the response, and you know which of the two problems you have.

Four places people try to fix it

Ordered by how close the fix sits to your browser. The first two make the symptom go away on your machine, which is useful and is not the same thing as the call being allowed.

What to check before you call it a CORS problem

In the order that rules out the most for the least effort.