CORS Isn't Blocking You — Your Browser Is. Here's What's Actually Happening

You've seen this error. The move: Google it, find the answer, paste some headers in, see if it goes away. Or the newer move: ask the AI, copy the four headers it hands you, paste them in. Maybe it worked. Maybe you added four headers and removed two and you're now afraid to touch it in case it breaks again.

But what's actually happening? In most cases, the server got your request. It responded. The data was ready. Your browser is the one blocking you from reading it. And for many modern API calls, your browser is sending a completely separate HTTP request before your actual one — one you never wrote, that doesn't appear anywhere in your code. If your server doesn't handle it, your real request never goes out.

This post covers why CORS exists, how it actually works, and how to diagnose issues instead of pasting headers until something changes.

TL;DR

• CORS is a browser enforcement mechanism, not a standalone security system. The server declares what it allows; the browser enforces it.
• An origin = protocol + hostname + port. All three. localhost:3000 and localhost:8000 are different origins.
• Postman has no CORS because it's not a browser. It's a direct HTTP client. These are separate questions.
• Simple requests go through immediately. Preflighted requests trigger an OPTIONS check first.
• Content-Type: application/json and Authorization both trigger a preflight.
• If the preflight returns 404, your real request never fires — and the console just says "CORS error".
• You cannot fix CORS from the client side. The policy lives on the server.

Why CORS Exists: The CSRF Attack

To understand CORS you need to understand the attack it was designed to contain: Cross-Site Request Forgery (CSRF).

Imagine you're logged into your bank. Session cookie is valid, sitting in the browser. You open another tab — any website. That page quietly runs this:

fetch("https://bank.com/transfer", {
  method: "POST",
  credentials: "include", // attach cookies automatically
  body: JSON.stringify({ amount: 5000, to: "attacker" })
});

The evil site can't read your bank cookie. But when it makes a request to bank.com, the browser automatically attaches your bank.com cookies to it. That's how cookies work — they travel with requests to their domain regardless of where the request originated.

The bank receives what looks like an authenticated request from you. Transfer goes through. You never clicked anything.

Modern browsers have made this harder, but the threat model still holds. Browsers established a rule: for many cross-origin requests, the browser protects the response. For more sensitive requests, there's a second layer that stops the request from leaving at all.

CORS didn't create the restriction. It created the exception. When a server sends the right CORS headers, it's explicitly saying: "I know this origin. I trust it. Let the response through."

The attacker can't fake that. They can fire cross-origin requests, but they cannot forge the server's response headers. The browser goes to the real server to ask. Only the real server can reply.

Origin Is Not Just a Domain

Most developers think origin means domain. It doesn't.

An origin is three things: protocol + hostname + port. All three must match for requests to be considered same-origin.

The path is completely irrelevant. The browser does not care about family resemblance between subdomains. It applies the same rules it would between two completely unrelated websites.

This is why your first CORS error almost always happens in local development. Frontend on port 3000, backend on port 8000. Same machine. Different origins. A developer makes the exact call in Postman — it works. Same call in the browser — CORS error. Nothing changed. That's intended behavior.

Why Postman Never Has CORS Errors

This deserves its own section because it causes genuine confusion.

Postman's desktop app makes HTTP calls directly to the server. No browser. No concept of an origin. No user session to hijack. No idea what other tabs you have open. Same as curl, same as wget. They're just programs talking to servers.

CORS is a browser feature because that's the only environment where untrusted code from the internet runs alongside your authenticated sessions. The CSRF attack needs three things: a browser, a live authenticated session, and untrusted code running in that same browser. Postman satisfies none of them.

⚠️ Warning: When debugging, Postman tells you whether the endpoint works. It tells you nothing about CORS. These are separate questions answered by separate tools.

Simple Requests vs Preflight Requests

The browser puts every cross-origin request into one of two categories.

Simple Requests

A request is "simple" when all three of the following hold:

• Method is GET, HEAD, or POST
• Headers are from a small standard set (no Authorization, no custom headers)
• If Content-Type is used, it must be application/x-www-form-urlencoded, multipart/form-data, or text/plain

application/json is not on that list.

For simple requests, the browser sends the request directly. The server responds. If the right CORS header is present, JavaScript reads the response. One round trip.

💡 Tip: These constraints aren't arbitrary. They exactly match the kinds of requests HTML forms could always make since the early web — before any of this existed. The browser doesn't add friction there because that attack surface always existed and servers were always expected to handle it.

Preflight Requests

The moment you violate any of the simple request conditions, the browser inserts a permissions check. It sends an OPTIONS request to the same endpoint — one you never wrote, that doesn't appear in your code.

What triggers a preflight:

• Content-Type: application/json
• Authorization header
• PUT, DELETE, or PATCH methods
• Any custom request header

If your server has no handler for OPTIONS, it returns a 404. Preflight fails. Real request never fires. The console reports a CORS error.

The console does not say your OPTIONS route returned a 404. It just says CORS error. Open the Network tab, find the OPTIONS request, check its status. That's your actual problem.

The CORS Response Headers — What They Actually Do

Access-Control-Allow-Origin

Present on every response. Answers the browser's core question: is this origin allowed to see what came back?

# Allow any origin — fine for genuinely public APIs
Access-Control-Allow-Origin: *
 
# Allow a specific origin
Access-Control-Allow-Origin: https://app.example.com
Vary: Origin

⚠️ Warning: You cannot comma-separate multiple origins. The spec allows one value or the wildcard. For multiple origins (production + staging), maintain an allowlist on the server, check the incoming Origin header, and echo back the matching one. Always add Vary: Origin if you're doing this — without it, a CDN may cache the response for one origin and serve it to another. Hard to reproduce, hard to trace.

Access-Control-Allow-Methods

Preflight response only. Declares which HTTP methods the server accepts.

Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS

If your actual request uses a method not listed, the preflight fails before your request goes out.

Access-Control-Allow-Headers

Declares which request headers the server accepts. This is the most common CORS misconfiguration after switching to JSON.

Access-Control-Allow-Headers: Content-Type, Authorization, X-Custom-Header

You've probably hit this: GET works fine. You switch to POST with a JSON body, CORS error. You didn't change the server. You didn't change the response headers. Almost always the same cause — Content-Type: application/json wasn't declared in Allow-Headers. The server's capability to handle that header and its CORS declaration of it are entirely separate things.

Access-Control-Allow-Credentials

You're likely to encounter this when moving from JWT tokens to session cookies.

# Server side
Access-Control-Allow-Credentials: true
 
# Client side — both required
fetch(url, { credentials: "include" })

By default, cross-origin requests don't include cookies or HTTP credentials. JWTs in Authorization headers worked. You switched to cookie-based sessions, it stopped. This header is why.

⚠️ Warning: When Allow-Credentials: true, you cannot use * for Allow-Origin. The browser rejects that combination — it's in the spec and won't change. If any origin could make credentialed requests as your users, you're right back to the CSRF problem CORS was built to prevent.

Access-Control-Expose-Headers

The one you find out about after shipping.

Even after a CORS check passes and the response reaches your JavaScript, the browser controls which response headers your code can actually read. Only these are readable by default:

• Cache-Control
• Content-Language
• Content-Length
• Content-Type
• Expires
• Last-Modified
• Pragma

Anything outside this list — custom headers, rate limit data, request IDs — returns null when your code tries to read it. No error. No warning. Just null.

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

Check this before you ship.

The Full Header Picture

Debugging CORS Errors: The Actual Process

The console gives you a summary. The Network tab gives you evidence.

1. Open the Network tab — not the console.
2. Look for an OPTIONS request to the same endpoint. Did it fire?
3. Check its status. If 404 → your server has no OPTIONS handler. That's your problem, not your headers.
4. If preflight returned 200, check Access-Control-Allow-Origin, Allow-Methods, Allow-Headers in the response. Do they match exactly what your request is sending?
5. If no preflight, check if Access-Control-Allow-Origin is present in the main response and exactly matches the request's Origin.

Production Checklist

1. Set Access-Control-Allow-Origin dynamically for multiple trusted origins — maintain an allowlist, echo back the match, add Vary: Origin.
2. Handle OPTIONS explicitly — don't rely on your framework's default catch-all. Respond with 200 or 204.
3. List every custom request header in Access-Control-Allow-Headers — Authorization, Content-Type, and anything else your client sends.
4. Set Access-Control-Allow-Credentials: true only when you actually need cookies or HTTP credentials — and never combine with *.
5. Declare Access-Control-Expose-Headers for any custom response headers your frontend reads.
6. Cache preflight responses with Access-Control-Max-Age to reduce OPTIONS round trips in production.
7. Test from the browser, not Postman, for CORS-specific issues. They are separate tools answering separate questions.

Conclusion

CORS errors feel mysterious because the console is aggressively unhelpful. "No Access-Control-Allow-Origin header is present" doesn't mean your code is broken. It means the server hasn't told the browser what it allows, and the browser is faithfully enforcing the absence of a declaration.

Your browser is running code from hundreds of websites simultaneously on behalf of a user who is logged into their bank and their email. The same-origin policy is what keeps those contexts from colliding. CORS is how servers deliberately open a gap in that wall when they actually mean to.

Server declares. Browser enforces. Your job is to make sure those two are aligned — and to open the Network tab instead of the console when they're not.