"CORS error" is probably one of the most misunderstood errors in web development, because it shows up on the client but is almost always fixed on the server, and because the message printed in the console never actually describes the real cause. Understanding that CORS is a browser security policy, not an API one, completely changes how you debug it.
CORS doesn't protect the API
The core misunderstanding: CORS does not protect the server from malicious requests. Any tool that isn't a browser (curl, Postman, a backend script, fetch from another server) completely ignores CORS and can call the API without restriction. CORS is a rule enforced by the browser to protect the user: it prevents a malicious site A from reading the response of a request made on the user's behalf to site B (their bank, their email), using session cookies already present in their browser.
In most cases the request actually does reach the server. What the browser blocks is reading the response from the JavaScript code that initiated the call, when the server hasn't explicitly authorized the calling origin.
The exact mechanism: "same-origin" and what triggers it
Two URLs share the same origin only if the scheme, domain and port are all strictly identical. https://app.example.com and https://api.example.com are two different origins, even if they belong to the same company and the same wildcard certificate. That difference is exactly what triggers CORS the moment the frontend calls the API on a separate subdomain, a different local dev port (localhost:3000 calling localhost:8000), or a third-party domain.
The preflight request: the most misunderstood part
For certain requests, the browser doesn't send the actual request directly. It first sends an OPTIONS request, called a preflight, asking the server whether it allows this exact combination of method, headers and origin. This gets triggered the moment a request goes beyond the scope of a "simple request" (GET/POST/HEAD with a basic content type and no custom headers): typically any request with Content-Type: application/json, a PUT/PATCH/DELETE method, or an Authorization header.
OPTIONS /api/users HTTP/1.1
Origin: https://app.example.com
Access-Control-Request-Method: PATCH
Access-Control-Request-Headers: content-type, authorization
The server has to respond with headers that explicitly allow this combination, otherwise the browser cancels the real request before it's even sent:
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE
Access-Control-Allow-Headers: content-type, authorization
Access-Control-Max-Age: 86400
This is why you often see, in the Network tab, an OPTIONS request returning 200 or 204, while the PATCH request that was supposed to follow never shows up at all: the browser blocked it locally, it was never even sent.
Diagnosing it properly
The error message in the console ("No 'Access-Control-Allow-Origin' header is present") describes a symptom, not a cause. Before touching the server configuration, inspect the Network tab:
- Does the
OPTIONSrequest even exist, and exactly what headers does it return? - If it returns a 401/403/500, the problem is probably not CORS at all, but an authentication middleware that also runs on preflight requests and rejects them (a very common trap).
- Does the returned
Access-Control-Allow-Originheader match exactly the calling origin (scheme + domain + port)?
curl -i -X OPTIONS https://api.example.com/users \
-H "Origin: https://app.example.com" \
-H "Access-Control-Request-Method: PATCH"
This command reproduces exactly what the browser does and shows the server's raw response, without the ambiguity of the console message.
The most common configuration mistakes
Access-Control-Allow-Origin: * with credentials
The CORS spec explicitly forbids combining * with Access-Control-Allow-Credentials: true. If the API needs to receive session cookies or an Authorization header, the wildcard simply doesn't work, and the server must dynamically reflect the exact requesting origin (after checking it against a whitelist), never a literal *.
// Express - correct configuration example with credentials
const allowedOrigins = ["https://app.example.com", "https://admin.example.com"];
app.use((req, res, next) => {
const origin = req.headers.origin;
if (allowedOrigins.includes(origin)) {
res.setHeader("Access-Control-Allow-Origin", origin);
res.setHeader("Access-Control-Allow-Credentials", "true");
}
next();
});
Forgetting Access-Control-Expose-Headers
Even when a request succeeds, JavaScript can only read the response headers explicitly listed through Access-Control-Expose-Headers. A custom header like X-Total-Count (common for pagination) will be invisible on the client side until it's listed, even though the request succeeds with no visible CORS error.
Configuring CORS at the application level while a reverse proxy already adds its own headers
When Nginx or an API Gateway also adds its own CORS headers on top of what the application (Laravel, Express, Django) already returns, the browser can end up receiving two duplicate values for Access-Control-Allow-Origin, which is treated as invalid and blocks the request even though each layer's configuration looks correct in isolation.
The tradeoffs of a restrictive configuration
Restricting Access-Control-Allow-Origin to a precise whitelist is the right practice, but it has a real operational cost: every new environment (a PR preview, a new client subdomain, a staging environment) has to be explicitly added to the list, or the configuration needs to be driven by an environment variable rather than hardcoded. Plenty of teams give in and fall back to * out of fatigue; that's acceptable for a read-only public API with no cookies and no sensitive header-based authentication, never for an API that handles sessions or user data.
When CORS isn't actually the problem
If a request fails with a generic network error (Failed to fetch, no explicit CORS message) and no request even shows up in the Network tab, the problem usually lies elsewhere: an invalid TLS certificate, an unreachable server, Mixed Content (an HTTPS page calling an HTTP resource), or a Content Security Policy blocking the request before it even reaches CORS logic. Adding CORS headers fixes nothing in these cases, and burning time iterating on CORS configuration while the request never actually leaves the browser is the single most common diagnostic mistake on this topic.
The CDN cache trap and the Vary header
When a response passes through a CDN or an intermediate HTTP cache (Cloudflare, Varnish, an application-level cache), and the server dynamically reflects the calling origin in Access-Control-Allow-Origin, adding a Vary: Origin header to the response becomes essential. Without it, the cache can store the response generated for the first origin that requested it, then serve that exact same response to a second, different origin, which causes either a CORS block (the cached origin doesn't match the actual caller) or, worse, a data leak to an origin that shouldn't have access if the response contains user-specific data.
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com
Vary: Origin
Cache-Control: public, max-age=3600
This bug never shows up in local development (no intermediate cache) and only appears in production, intermittently, depending on the order requests happen to hit a given cache node, which makes it one of the hardest CORS bugs to reproduce.
fetch and no-cors mode: a silent client-side trap
One last trap comes from the client itself: calling fetch(url, { mode: "no-cors" }) does not bypass CORS, despite what the name suggests. This mode allows the request to be sent without a CORS check, but makes the response completely opaque to the calling JavaScript: status, headers and body all become unreadable, even though the request technically succeeded at the network level. A developer who adds this mode to "silence" the CORS error in the console ends up with code that runs without a visible error, but that can never read the data it received, which is often harder to diagnose than an explicit block.
Takeaway: CORS protects the user, not the server, which is exactly why curl works when the browser refuses. Always check the OPTIONS request and its raw response before touching the configuration, and never combine Access-Control-Allow-Origin: * with credentials.
