That message means your browser sent an OPTIONS preflight to a different origin, and the reply did not include an Access-Control-Allow-Origin header matching your page. The server owns this fix, not the frontend. If you control the API, add the header and allow the method and headers; if you don't, you need a proxy or a CORS-enabled endpoint.
This is the single most common wall developers hit when a fetch() or XMLHttpRequest crosses origins. The error text is long, and that length hides the useful part. Read it carefully: "response to preflight request doesn't pass access control check" tells you the browser blocked the request before it ever sent your POST, PUT, or DELETE. Nothing reached your endpoint logic. Your data isn't wrong. Your auth token isn't wrong. The server's response headers are incomplete.
The console message varies by browser. Chrome, Edge, and Firefox each word it slightly differently, and Safari is terser still, but the underlying cause is identical: the CORS check failed on either the preflight or the actual response. Once you learn to decode which one, the fix usually takes less time than reading this introduction.
One boundary up front: CORS is a browser-enforced policy. It is not authentication, it is not a security boundary against non-browser clients, and it does nothing to protect your API from curl, Postman, or a server-side script. A misconfiguration here is a usability problem and sometimes a data-exposure problem, but the mechanism exists to stop one origin's JavaScript from reading another origin's responses without permission.
The Preflight Request Is a Separate Round Trip Your Code Never Sees
When your page at https://app.example.com calls https://api.example.com/orders with a Content-Type: application/json header or an Authorization header, the browser classifies the request as non-simple. It then sends an OPTIONS request first, with Origin, Access-Control-Request-Method, and Access-Control-Request-Headers set. Your fetch() call pauses. DevTools shows the OPTIONS in the network panel only if you haven't filtered it out. Many developers miss it entirely because the fetch promise resolves as a failure with no response body.
That OPTIONS request must come back with 204 or 200 and three headers: Access-Control-Allow-Origin matching your page's origin exactly, Access-Control-Allow-Methods including the method you're using, and Access-Control-Allow-Headers including every custom header you sent. If any one of those is missing or mismatched, the browser aborts, and the console prints the error you searched for.
Simple requests skip the preflight. A GET or POST with Content-Type of application/x-www-form-urlencoded, multipart/form-data, or text/plain, and no custom headers, goes straight through. That's why your plain form post works while your JSON fetch() fails. The preflight is the difference.
Watch for one edge case: if the preflight succeeds but the actual response omits Access-Control-Allow-Origin, you get a different but related message about the actual response. Both live under the same family of errors, and the fix is the same header set on the real response, not just the OPTIONS handler.
Adding Access-Control-Allow-Origin on the Server You Control
If you own the API, this is a 15-minute fix in most frameworks, and the exact configuration depends on the stack. The header must echo the requesting origin or a wildcard, and it must appear on both the preflight response and the actual response. Many servers handle the OPTIONS correctly and forget the second half.
Express with the cors package is the most common setup:
Spring Boot 3.x accepts @CrossOrigin(origins = "https://app.example.com") on the controller, or a global WebMvcConfigurer with addCorsMappings. Django handles it with django-cors-headers, setting CORS_ALLOWED_ORIGINS. Flask uses flask-cors and the CORS(app, origins=[...]) call. ASP.NET Core uses app.UseCors() with a policy built in builder.Services.AddCors().
The trap in every one of those stacks: an Authorization header triggers the preflight, and if allowedHeaders doesn't list it, the preflight fails. Add every custom header you send. If you send X-Request-Id, list it. If you send X-CSRF-Token, list it.
Credentials add a second requirement that breaks more setups than anything else. If your fetch includes credentials: 'include', the server cannot respond with Access-Control-Allow-Origin: *. It must echo the exact origin, and it must also send Access-Control-Allow-Credentials: true. A wildcard origin plus credentials is rejected by every browser without exception.
Why Setting the Header in Your Frontend Code Does Nothing
A fetch() call's headers object sets request headers, not response headers. Adding 'Access-Control-Allow-Origin': '*' to that object sends the header to the server as a request header, where it means nothing and is often rejected by the preflight check because it isn't in Access-Control-Allow-Headers. The response headers are set by the server and read by the browser. JavaScript running in the page cannot add, remove, or modify them.
This matters because a shocking number of Stack Overflow answers suggest exactly that. It doesn't work. It never worked. If a forum post tells you to add the header client-side, close the tab.
The one legitimate client-side lever is mode: 'no-cors'. That flag changes the request to an opaque type where the browser hides the response body from your code. The request goes out, but you cannot read the reply. It is useful for firing a beacon or loading an image, and it is useless for reading JSON. If you see no-cors recommended for an API call, it's a wrong answer.
Similarly, mode: 'cors' is the default for cross-origin fetch(). Setting it explicitly changes nothing. The failure is server-side.
Choosing Between a Dev Proxy, a Production Reverse Proxy, and CORS on the API
When you cannot modify the upstream API, you have three realistic workarounds. They trade off differently, and the right choice depends on whether the workaround needs to survive into production.
| Approach | Scope | Setup effort | Survives deployment | Works with credentials |
|---|---|---|---|---|
| Vite server.proxy | Local dev only | 2 minutes | No | Yes, if proxy rewrites origin |
| Next.js rewrites() | Dev and production (self-hosted or Vercel) | 10 minutes | Yes | Varies by host |
| Nginx proxy_pass | Production | 20 minutes | Yes | Yes, with header rewrite |
| Cloudflare Worker | Production | 15 minutes | Yes | Yes |
| Public CORS proxy (cors-anywhere et al.) | Prototyping | 1 minute | Not recommended | No |
| Server-side fetch (Node, Python, etc.) | Anywhere | Varies | Yes | N/A |
The Vite proxy is the fastest dev fix. Set server.proxy in vite.config.ts:
Then fetch /api/orders from your frontend. The browser sees a same-origin request. The Vite dev server makes the cross-origin call server-side, where CORS doesn't apply. Fast, clean, and useless in production because the proxy only runs in the dev server.
Next.js rewrites() is similar but lives in next.config.js and works in production if you're hosting on Vercel or a self-hosted Next server. That's a genuine advantage for small projects. It's not a solution if your frontend is a static index.html on S3.
A production Nginx proxy is the robust choice if you own the frontend's hosting. You reverse-proxy /api/ to the upstream, and the browser sees a same-origin request. Add proxy_set_header Origin https://api.example.com; if the upstream rejects unknown origins.
Cloudflare Workers are worth mentioning because they sit between the browser and the API, run JavaScript on Cloudflare's edge, and let you add CORS headers to responses from APIs you don't control. The free tier is generous. If the API accepts requests from anywhere but doesn't send the headers, a Worker fixes it in about 15 minutes.
Public CORS proxies like the original cors-anywhere are a prototyping tool. They route your traffic through a third party's server and should never be used with auth tokens or real user data. Several have been shut down or rate-limited because of abuse.
Verifying the Fix in Browser DevTools and Curl Before You Deploy
Test the preflight manually before you test it in the browser. A curl command that mimics what the browser sends will tell you instantly whether your server responds correctly.
The response should show 204 or 200, plus the three Access-Control-Allow-* headers. If it doesn't, your server isn't handling OPTIONS at all, or it handles it but the CORS middleware isn't wired in.
In DevTools, open the Network tab, uncheck "Hide preflight requests" if the filter is hiding them, and reload. The OPTIONS request appears before the real one. Click it, look at the response headers, and compare what the browser asked for with what the server sent back. The Chrome console error usually specifies which header is missing β read past the boilerplate sentence to that detail.
A useful sanity check: the Origin header the browser sends is not spoofable from JavaScript. If the API is behind auth and returns data to Origin: https://evil.example.com, that's a real data leak, not a CORS bug. The header is set by the browser and reflects the page's actual origin.
Wildcard Origin, Credentials, and the Configuration That Fails Silently
The wildcard-plus-credentials combination is the most common silent failure in production CORS. The setup works in dev because the developer isn't sending cookies or auth headers yet, then breaks the moment login ships. The browser refuses Access-Control-Allow-Origin: * when credentials: 'include' is set, and no override exists.
The fix is to echo the origin. In Express, use a function for the origin option that reflects req.headers.origin after checking it against an allowlist. In Spring, allowCredentials(true) must be paired with allowedOrigins("https://app.example.com"), not *. In Django, CORS_ALLOW_CREDENTIALS = True with CORS_ALLOWED_ORIGINS set to specific URLs.
Subdomain wildcards introduce their own trap. Access-Control-Allow-Origin: https://*.example.com is not valid syntax and will not match. Some servers implement origin reflection with a substring check, which is a security problem β a malicious https://evil-example.com matches a naive endsWith('example.com') check. Use proper URL parsing to extract the hostname and match against an explicit allowlist.
Another failure: some CDNs and load balancers strip or rewrite headers. If your app server sends the correct CORS headers but the CDN in front doesn't forward them, the browser sees nothing. Reproduce the request against the origin server directly (via its IP or internal hostname) to isolate whether the header is being lost in transit. Check the CDN's documentation for header handling β many have specific CORS settings in the dashboard.
Caching adds its own wrinkle. If a 204 preflight response is cached for hours by the browser, and you then change the allowed headers on the server, users with cached responses see stale behavior until the cache expires. Set Access-Control-Max-Age deliberately β 600 seconds is a common and safe choice; 86400 is risky during development.
When You Can't Control the API, and the Five-Step Diagnostic Order That Saves Time
Some APIs are third-party, and the vendor simply refuses to add CORS headers. In that case the correct production architecture is a server-side fetch. Your backend makes the call to the third-party API, gets the JSON, and returns it to your frontend on the same origin. The browser never makes the cross-origin call, so CORS never enters the picture.
This pattern also solves the credentials problem: your server can hold the API key and never expose it to the client. It's not a workaround; it's the correct pattern for integrating APIs whose credentials shouldn't live in your JavaScript.
For debugging the general case, work through these five checks in order:
1: Confirm the preflight is the failing request. In DevTools, network panel, look for the OPTIONS. If it's missing, your request was simple and failed on the actual response. If it's present and red, that's the failing one. 2: Run the curl check with the exact origin and headers. This is ground truth. The server either sends the right headers or it doesn't. 3: Read the browser error detail past the boilerplate. Chrome names the specific header mismatch. Firefox does too, sometimes tersely. Don't stop at "blocked by CORS policy." 4: Check whether any middleware is short-circuiting. Some auth middleware returns a 401 on the OPTIONS request before the CORS layer runs. Order matters in Express, Spring, and ASP.NET. CORS middleware must run before auth middleware. 5: Isolate CDN and proxy layers. Hit the origin server directly to confirm the headers exist. Then check them on the CDN'd hostname. If they disappear, the CDN is the culprit.
The 401-on-preflight case breaks more deployments than people realize. Your token is sent in the actual request, not the preflight, so an auth middleware that runs before CORS sees an unauthenticated OPTIONS and returns 401. The browser interprets any non-2xx preflight as a CORS failure and reports it as a missing Access-Control-Allow-Origin header even though the real problem is auth. Reordering the middleware usually fixes it.
FAQ
Does adding Access-Control-Allow-Origin to my fetch headers fix the error?
No, and adding it to the request can make things worse. Request headers are read by the server; response headers are read by the browser. JavaScript can't set response headers on a cross-origin request, so this header must come from the server. If you add it to your headers object in fetch(), some servers will reject the request because Access-Control-Allow-Origin isn't in their Access-Control-Allow-Headers list.
Why does the request work in Postman but fail in the browser?
Postman is not a browser and does not enforce CORS. It sends the request regardless of the headers. The browser runs a preflight first and only forwards the request if that preflight passes. This is why "works in Postman" is never evidence that a browser will work β the two use different governance rules, and the browser is stricter.
Is CORS actually protecting my API from unauthorized access?
No. CORS is a browser policy that prevents one origin's JavaScript from reading another origin's responses. It does nothing against curl, Postman, server-to-server calls, or malicious scraping tools. Authorization must be enforced by tokens, API keys, rate limits, and server-side validation. Confusing CORS with auth is one of the more dangerous conceptual errors in web security.
What's the difference between a missing header on preflight versus on the actual response?
The preflight is the OPTIONS check that runs before the real request. The actual response is the one that carries your data. Both must include Access-Control-Allow-Origin. If the preflight passes but the actual response omits the header, the browser blocks the response body, and you see a related error. The fix is the same header on both responses, not just the OPTIONS handler β a point that gets skipped in a lot of tutorials.
Can I use a public CORS proxy like cors-anywhere?
Only for prototyping without sensitive data. Public CORS proxies route your traffic through a third party, which means they see your requests, your headers, and your payloads. Never use one with auth tokens, user data, or anything you wouldn't put in an email to a stranger. Several have been shut down or rate-limited for abuse. The correct production pattern is a reverse proxy or a Cloudflare Worker under your control.
Why does my Authorization header trigger the CORS error when other headers don't?
Authorization is not in the browser's list of simple headers, so a request that includes it is classified as non-simple and triggers the preflight. The OPTIONS response must then include Authorization in Access-Control-Allow-Headers. If it doesn't, the preflight fails and you see the error. The fix is server-side: add Authorization to the allowed headers list on your CORS configuration.
How much does fixing this cost in time?
For an API you own, the fix is typically 10β30 minutes of configuration and testing, assuming you have server access. For a third-party API you don't control, a proxy layer β Nginx, Worker, or backend pass-through β runs 15 minutes to an hour of setup depending on your stack. The expensive case is when the issue hides behind a CDN that strips headers; that adds a debugging session and often requires a support ticket.
This article is general technical information, not a security or compliance opinion for your specific system. CORS configuration interacts with authentication, authorization, and data exposure, and getting it wrong can be harmless or serious depending on what the API serves. For systems handling sensitive user data, regulated industries, or public APIs, have a qualified security professional review the configuration before deployment. If you suspect an active data exposure rather than a configuration nuisance, treat it as a security incident and follow your organization's incident response process.