CORS Explained Once and For All: What Developers Always Get Wrong

The Error Everyone Copy-Pastes Into Stack Overflow

You call your API from the frontend, open DevTools, and there it is: a red error about a missing Access-Control-Allow-Origin header. The request never even reaches your route handler's logic — or worse, it does reach it, runs a database write, and the response still gets thrown away by the browser. That disconnect is exactly where most of the confusion around CORS comes from, so it's worth clearing up before touching any code.

CORS — Cross-Origin Resource Sharing — is not a bug, not a bad library, and not something you can fix by installing an npm package on the frontend. It's a browser security feature, enforced entirely client-side, that exists to protect users, not APIs. Understanding that one fact resolves most of the frustration.

The Same-Origin Policy, and Why CORS Exists At All

Browsers enforce something called the same-origin policy: by default, JavaScript running on https://app.example.com cannot read responses from https://api.other-domain.com. Two URLs share an origin only when the scheme, host, and port all match exactly — http versus https counts as a different origin, and so does a different subdomain or port.

Without this rule, a malicious site you visit could quietly run JavaScript in the background that calls your bank's API using your logged-in session cookies, reads the response, and exfiltrates your balance — all without you clicking anything. The same-origin policy is what stops that. CORS is the mechanism that lets a server deliberately punch a controlled hole in that wall for origins it actually trusts.

What Actually Happens on the Wire

A cross-origin request goes through one of two paths, and knowing which one you're hitting explains a lot of otherwise-confusing behavior.

Simple Requests

A request qualifies as "simple" when it uses GET, HEAD, or plain-form POST, sends only a small set of standard headers, and has a content type of application/x-www-form-urlencoded, multipart/form-data, or text/plain. The browser sends it directly and just checks the response headers before deciding whether to hand the data to your JavaScript.

Preflighted Requests

Almost everything else — a JSON POST, PUT, DELETE, requests carrying an Authorization header, custom headers like X-Api-Key — triggers a preflight. Before sending your actual request, the browser fires off an OPTIONS request asking the server, in effect, "if I send this, will you allow it?" Only if the server answers correctly does the browser send the real request.

OPTIONS /api/orders HTTP/1.1
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type, authorization

--- server must respond with ---

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: content-type, authorization
Access-Control-Max-Age: 86400

This is why you'll sometimes see two network requests for what looks like a single API call in your code — that's expected, not a bug.

The Headers That Matter

The Mistakes Developers Make Over and Over

1. Wildcarding the origin while also allowing credentials

Setting Access-Control-Allow-Origin: * is fine for a public, unauthenticated API. But the moment you also need Access-Control-Allow-Credentials: true — for cookies, sessions, or browser-stored auth — browsers reject the combination outright. A wildcard origin plus credentials is treated as a security hole, so you have to echo back the specific requesting origin instead of using a wildcard.

2. Trying to "fix" CORS from the frontend

No frontend fetch option, Axios config, or browser extension permanently solves a CORS error for your actual users — the browser is enforcing a policy the server has to grant, not one the client can waive. Disabling web security in your own local Chrome instance might get you through a demo, but it does nothing for anyone else hitting your production site.

3. Forgetting the preflight route entirely

If your framework doesn't automatically respond to OPTIONS requests, the preflight fails before your real handler ever runs, and the browser reports a generic CORS failure that has nothing to do with your actual endpoint logic. Confirm your server — or your API gateway, load balancer, or CDN in front of it — actually answers OPTIONS correctly.

4. Assuming CORS is an authentication or authorization mechanism

CORS decides whether a browser is allowed to expose a response to page JavaScript. It says nothing about whether the request itself was authorized. A misconfigured but "open" CORS policy doesn't let attackers steal data using tools like curl or Postman, since those don't enforce CORS at all — but it can absolutely let a malicious website trick a logged-in victim's browser into making authenticated requests on their behalf. Treat CORS and your actual auth checks as two separate, both-necessary layers.

5. Allowlisting origins with string matching instead of exact comparison

A naive check like origin.includes("example.com") will happily match evil-example.com.attacker.net. Compare against an exact, explicit list of allowed origins, not a substring or regex that can be gamed.

Configuring CORS Correctly in a Next.js API Route

For a Next.js API route or route handler, set the headers explicitly and handle OPTIONS yourself:

// app/api/orders/route.js
const ALLOWED_ORIGINS = [
  "https://app.example.com",
  "https://staging.example.com",
];

function corsHeaders(origin) {
  const allowed = ALLOWED_ORIGINS.includes(origin) ? origin : "";
  return {
    "Access-Control-Allow-Origin": allowed,
    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
    "Access-Control-Allow-Headers": "Content-Type, Authorization",
    "Access-Control-Allow-Credentials": "true",
    "Vary": "Origin",
  };
}

export async function OPTIONS(request) {
  const origin = request.headers.get("origin") || "";
  return new Response(null, { status: 204, headers: corsHeaders(origin) });
}

export async function POST(request) {
  const origin = request.headers.get("origin") || "";
  const body = await request.json();

  // ... your actual logic here

  return Response.json(
    { success: true },
    { headers: corsHeaders(origin) }
  );
}

The Vary: Origin header matters more than it looks — without it, shared caches and CDNs can serve one user's CORS-approved response to a different origin that should have been rejected.

Debugging a CORS Error Methodically

1. Open the Network tab and find the actual failing request — check if there's a separate OPTIONS request and whether it returned a 2xx status.
2. Inspect the response headers on that request. No Access-Control-Allow-Origin header at all means the server isn't setting CORS headers for this route — start there.
3. Confirm the allowed origin in the response exactly matches the page's origin, including scheme and port.
4. If you're sending cookies or auth, confirm both Access-Control-Allow-Credentials: true on the server and credentials: "include" on the client fetch call are set — both sides have to opt in.
5. Check whether a reverse proxy, API gateway, or CDN in front of your app is stripping or overwriting your CORS headers before they reach the browser.

The Takeaway

CORS is a browser-side gatekeeper, not a network firewall, and it's entirely configured by the server that owns the resource being requested. Once you separate that from your actual authentication and authorization logic — and stop trying to silence the error from the client — the errors stop being mysterious. Set an explicit origin allowlist, handle preflight requests correctly, only pair wildcard origins with unauthenticated endpoints, and CORS becomes one of the more predictable parts of your stack instead of the thing that eats your afternoon.