← All posts
Nov 18, 2026 · 7 min read

How CORS Actually Works

Why the browser blocks your request, what a preflight is, and how to debug the error without guessing.

#web#backend#tutorial
--

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.

CORS / a round trip

The server permits. The browser checks.

Your browser
app.example.com
API server
api.example.com
  1. Browser sends a simple request

    Origin: https://app.example.com
  2. Server returns data and permission

    Access-Control-Allow-Origin: https://app.example.com
  3. Browser checks the response headers

    Origin allowed

    The page can read the response data.

    Missing or wrong permission

    The browser hides the response from the page, even if the server returned it.

Need a preflight first?

For requests with JSON, Authorization, or methods like PUT, the browser asks permission before sending the real request.

OPTIONS preflightServer allows itReal request is sent

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.

Simplified flow without credentials. Both origins use HTTPS. CORS reference ↗
What I assumed
CORS stops requests from reaching my server.
What actually happens
The browser stops the page from reading the response. The server decides what to allow, and the browser enforces it.

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.

Preflight, simplified
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: authorization

The headers that matter

HeaderWhat it does
Access-Control-Allow-OriginWhich origin may read the response. One exact origin, or * for anyone.
Access-Control-Allow-MethodsWhich methods are allowed on the real request.
Access-Control-Allow-HeadersWhich request headers the page may send, such as Authorization.
Access-Control-Allow-CredentialsLets the page send cookies, if it also asks for them.
Access-Control-Max-AgeHow long the browser may cache the preflight answer.

Setting it up in Express

server.js
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.

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

Mistakes that cost me time

  1. 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.
  2. 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.
  3. 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.
  4. 04An origin that is almost righthttp vs https, a trailing slash, a different port, or www vs no www. The comparison is exact.
  5. 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.

The takeaway

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.

Next postVibe Coding vs AI-Assisted Coding
Book a call
patr1ck@dev — zsh
patr1ck.dev shell — type `help` to begin.
❯