Introduction: The Red Line Every Frontend Developer Has Seen#

If you’ve ever worked on a project with a separated frontend and backend, you’ve almost certainly seen this in the console:

1
Access to fetch at 'https://api.example.com/api/users' from origin
2
'https://app.example.com' has been blocked by CORS policy:
3
No 'Access-Control-Allow-Origin' header is present on the requested resource.

This is the cross-origin problem. It shows up extremely often, yet it’s always glossed over as “the backend isn’t configured properly.” This article takes apart the CORS mechanism from the ground up, then lands on configuration and troubleshooting for three backend frameworks, so that next time you see this red line, you won’t be relying on “just add a *” and hoping for the best.

1. Prerequisite Concept: Same-Origin Policy#

Browsers have an iron rule—the Same-Origin Policy. It states: scripts in a page can only read responses from “same-origin” resources.

The criterion for “same-origin” is that three parts match exactly: scheme + host + port. If any one of the three differs, it’s cross-origin:

Note that the path and query parameters do not participate in the same-origin determination—/a and /b are always same-origin.

The purpose of the same-origin policy is security: without it, any website could use your cookies to request your online banking, email, and read the results. It is the cornerstone of browser security, but at the same time it blocks the “legitimate” separated frontend-backend scenario—the frontend runs on localhost:5173, the backend runs on localhost:3000, and a different port means cross-origin.

CORS (Cross-Origin Resource Sharing) is the door the browser opens for “legitimate cross-origin”: the server explicitly declares through response headers “which origins may access me.”

2. Two Kinds of Requests: Simple Requests vs Preflight Requests#

CORS divides cross-origin requests into two categories, handled in completely different ways, and this is the key to understanding all error messages.

Simple Request—when all of the following conditions are met, the browser sends the request directly:

• The method is one of GET, HEAD, POST;
• Only request headers from the “safe list” are used, such as Accept, Accept-Language, Content-Language, and Content-Type whose values are limited to application/x-www-form-urlencoded, multipart/form-data, text/plain;
• No ReadableStream, XMLHttpRequest.upload event listeners, etc. are used.

A simple request does not trigger an extra request; the browser simply “acts first and reports later”—the request is sent as usual, but whether the response can be read by the script depends on whether the response headers include Access-Control-Allow-Origin.

Preflight Request—as long as any one of the above conditions is not met, the browser first sends a OPTIONS request to “scout the way”:

1
OPTIONS /api/users HTTP/1.1
2
Origin: https://app.example.com
3
Access-Control-Request-Method: PUT
4
Access-Control-Request-Headers: content-type, authorization

The server must return the allowed methods and headers for this OPTIONS, and only then will the browser let the real request through. This is why you often see the same endpoint appear twice in the Network panel, one of them being OPTIONS.

3. Overview of Key Response Headers#

Configuring CORS is essentially just setting the following response headers:

There are two easily overlooked points:

1. Access-Control-Expose-Headers governs “reading response headers.” By default, a few headers such as Content-Type and Cache-Control in a cross-origin response can be read by JS, but your custom X-Total-Count, X-RateLimit-Remaining, etc. cannot be read—unless they are listed in Access-Control-Expose-Headers.

2. Access-Control-Max-Age governs “preflight caching.” The preflight request itself has overhead, so the browser caches the preflight result, for at most the number of seconds specified by Access-Control-Max-Age (the actual upper limit in Chromium is about 2 hours). This is both a performance optimization and a common culprit behind “I changed the config but it didn’t take effect.”

4. Server-Side Practical Configuration#

1
const express = require('express');
2
const cors = require('cors');
3

4
const app = express();
5

6
app.use(cors({
7
  // Only allow explicit whitelist entries, not a blanket *
8
  origin: ['https://app.example.com', 'https://admin.example.com'],
9
  credentials: true,                 // Allow credentials
10
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
11
  exposedHeaders: ['X-Total-Count'],
12
  maxAge: 3600,                      // Cache preflight results for 1 hour
13
}));
14

15
app.get('/api/users', (req, res) => {
16
  res.set('X-Total-Count', '42');    // Must be exposed for the frontend to read it
17
  res.json([{ id: 1, name: 'Alice' }]);
18
});
19

20
app.listen(3000);

1
const http = require('http');
2

3
const ALLOWED = new Set(['https://app.example.com']);
4

5
const server = http.createServer((req, res) => {
6
  const origin = req.headers.origin;
7

8
  // 1. Handle preflight requests
9
  if (req.method === 'OPTIONS') {
10
    const allowOrigin = ALLOWED.has(origin) ? origin : '';
11
    res.writeHead(204, {
12
      'Access-Control-Allow-Origin': allowOrigin,
13
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
14
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
15
      'Access-Control-Allow-Credentials': 'true',
16
      'Access-Control-Max-Age': '3600',
17
      'Vary': 'Origin',
18
    });
19
    res.end();
20
    return;
21
  }
22

23
  // 2. Normal requests: only allow if the origin is in the whitelist
24
  if (origin && ALLOWED.has(origin)) {
25
    res.setHeader('Access-Control-Allow-Origin', origin);
26
    res.setHeader('Access-Control-Allow-Credentials', 'true');
27
    res.setHeader('Vary', 'Origin');
28
  }
29

30
  res.setHeader('Content-Type', 'application/json');
31
  res.end(JSON.stringify({ ok: true }));
32
});
33

34
server.listen(3000);

1
location /api/ {
2
    if ($http_origin ~* "^https://(app|admin)\.example\.com$") {
3
        add_header 'Access-Control-Allow-Origin' "$http_origin" always;
4
        add_header 'Access-Control-Allow-Credentials' 'true' always;
5
        add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
6
        add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization' always;
7
        add_header 'Access-Control-Max-Age' '3600' always;
8
        add_header 'Vary' 'Origin' always;
9
    }
10

11
    if ($request_method = 'OPTIONS') {
12
        return 204;
13
    }
14
}

5. Cross-Origin with Credentials (Cookies)#

By default, cross-origin requests do not carry cookies. If your API relies on cookies for sessions, both sides need to cooperate:

Frontend: Set credentials: 'include' in fetch (or set withCredentials: true in axios):

1
fetch('https://api.example.com/api/me', {
2
  credentials: 'include',
3
})
4
  .then((res) => res.json())
5
  .then((data) => console.log(data));

Backend: Must echo the specific origin and add Access-Control-Allow-Credentials: true.

Here’s a high-frequency trap: when credentials are included, Access-Control-Allow-Origin cannot be *. The spec requires “either echo a specific origin, or don’t allow credentials”—the two are mutually exclusive. You’ll see a clear error like this in the console:

1
The value of the 'Access-Control-Allow-Origin' header in the response
2
must not be the wildcard '*' when the request's credentials mode is 'include'.

The solution is the whitelist echo approach from the earlier example: grab Origin, check if it’s in the whitelist, and if so, echo it back as-is.

6. Classic Error Reference Table#

There are two “truths” worth remembering when troubleshooting:

1. CORS is browser behavior, not server behavior. Requesting the API with curl or Postman always “works” because they don’t enforce the same-origin policy at all. So “Postman works but the browser doesn’t” doesn’t mean the backend is broken—it just means the CORS headers aren’t configured.

2. Simple requests are “sent but unreadable”. The browser sends the request, the server processes it, but the response is blocked by the browser and not handed to JS. So for simple request cross-origin issues, you’ll see the request succeed (200) in the Network panel but CORS errors in the console—don’t be misled by “but the request succeeded!“

7. Two Advanced Traps#

Trap 1: null origin.

When a page is opened via the file:// protocol, or is inside an iframe with sandbox, the request’s Origin header is the string "null". If your whitelist is Set(['https://app.example.com']), it naturally won’t match—but some careless configurations write origin: 'null' to “allow” it, which effectively opens the door to any malicious local page opened from file://, creating a security vulnerability. The correct approach is to never accept null as a trusted origin.

Trap 2: The cost of blindly using *.

Writing Access-Control-Allow-Origin: * during development to save effort does make the errors disappear immediately, but it also means any website can read the public responses from that API. For purely public APIs that don’t involve credentials or sensitive data (such as public APIs and static resources), * is acceptable; once an API involves user data, you should use a whitelist.

Conclusion#

The difficulty of CORS was never about “adding a header”—it’s about understanding the three layers behind it: why the same-origin policy blocks requests, the difference between simple requests and preflight requests, and the boundary of responsibility between browser vs. server. Once you clarify these three points, the vast majority of cross-origin errors can be diagnosed within five minutes.

A practical closing suggestion: during development, instead of configuring CORS everywhere, use the frontend dev server’s proxy to forward /api to the backend (Vite, webpack, and CRA all have built-in proxy configuration), making the frontend and backend appear “same-origin” from the browser’s perspective, bypassing cross-origin issues at the root; then in production, properly configure the whitelist at the gateway layer. This way, the development experience is clean and production is secure.

References#

• MDN - Cross-Origin Resource Sharing (CORS)
• MDN - Same-origin policy
• RFC 6454 - The Web Origin Concept
• Fetch Specification - CORS protocol
• cors - Node.js middleware official documentation
• web.dev - CORS and security from the browser’s perspective