How CORS Actually Works
Why the browser blocks your request, what a preflight is, and how to debug the error without guessing.
There is a wall every web developer hits sooner or later: a request that works fine in Postman and then fails in the browser with a long error about CORS. It looks like the server is refusing you. I did not understand why until it caught me out early in my web dev journey, and the answer is that it is not the server, it is the browser.
First, the rule behind it
Browsers follow the same-origin policy: a page from one origin is not allowed to read responses from another origin by default. An origin is the scheme, the host and the port together, so https://app.example.com and https://api.example.com are different origins, and so are http and https, or port 3000 and port 4000. CORS, short for cross-origin resource sharing, is the way a server tells the browser which other origins are allowed to read its responses.
The server permits. The browser checks.
Browser sends a simple request
Origin: https://app.example.comServer returns data and permission
Access-Control-Allow-Origin: https://app.example.comBrowser checks the response headers
Origin allowedThe page can read the response data.
Missing or wrong permissionThe browser hides the response from the page, even if the server returned it.
For requests with JSON, Authorization, or methods like PUT, the browser asks permission before sending the real request.
If the preflight fails, the browser stops before the real request. After a successful preflight, the real response still needs to pass the CORS check.
That is also why a request can work in Postman or curl and fail in the browser. Those tools do not enforce the policy. Only browsers do.
Simple requests and preflights
For a simple request, such as a plain GET or a form-style POST, the browser sends it with an Origin header and then checks the response for Access-Control-Allow-Origin. Anything more involved gets a preflight first. That includes methods like PUT and DELETE, an Authorization header, or a JSON body, because Content-Type: application/json is not one of the simple types. The browser sends an OPTIONS request asking permission, and only sends the real request if the answer allows it.
OPTIONS /me
Origin: https://app.example.com
Access-Control-Request-Method: GET
Access-Control-Request-Headers: authorization
204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET
Access-Control-Allow-Headers: authorizationThe headers that matter
| Header | What it does |
|---|---|
| Access-Control-Allow-Origin | Which origin may read the response. One exact origin, or * for anyone. |
| Access-Control-Allow-Methods | Which methods are allowed on the real request. |
| Access-Control-Allow-Headers | Which request headers the page may send, such as Authorization. |
| Access-Control-Allow-Credentials | Lets the page send cookies, if it also asks for them. |
| Access-Control-Max-Age | How long the browser may cache the preflight answer. |
Setting it up in Express
import express from "express";
import cors from "cors";
const app = express();
app.use(
cors({
origin: "https://app.example.com",
credentials: true,
})
);On the client, cookies are only sent when you ask for them, and the browser only exposes the response if the server agrees.
fetch("https://api.example.com/me", {
credentials: "include",
});Mistakes that cost me time
- 01Wildcard with credentialsIf the request includes credentials, Access-Control-Allow-Origin cannot be *. It must name the exact origin, and the server must also send Access-Control-Allow-Credentials: true.
- 02Not answering the OPTIONS requestIf your server or framework rejects the preflight, the real request never goes out. Make sure OPTIONS gets a quick 2xx with the right headers.
- 03CORS headers only on successErrors need them too. If a 500 comes back without the headers, the browser reports a CORS error and hides the real one.
- 04An origin that is almost righthttp vs https, a trailing slash, a different port, or www vs no www. The comparison is exact.
- 05Treating CORS as security for the APIIt protects the user's browser from other sites reading responses. It does not replace authentication, and anyone can call your API without a browser.
How to debug it
Open the Network tab and look at the failing request. If there is an OPTIONS request before it, start there: check its status and its response headers. Then compare the Origin header the browser sent with the Access-Control-Allow-Origin it got back. Most of the time the answer is a mismatch you can see side by side. If you reflect the incoming origin dynamically, add a Vary: Origin header so caches do not hand one origin's answer to another.
CORS is the browser asking the server for permission on behalf of the user. Fix it on the server, and read the Network tab before changing anything.