CORS and Preflight: A Step-by-Step Debugging Guide
CORS errors are confusing partly because the request often reached the server and got a response, and the browser then refused to hand it to your code. This post explains the protocol and gives a repeatable order of checks for finding what went wrong.
CORS in brief
Browsers enforce the same-origin policy: JavaScript on origin A cannot read responses from origin B. CORS is how origin B opts in and says "origin A may read my responses."
The same-origin policy is the protection. Without it, a malicious page could read your bank's API responses using your logged-in cookies. Note what CORS does not do: it controls whether a page can read a response, and for simple requests the server still receives and processes the request. CORS is not a defense against cross-site request forgery. Use CSRF tokens and SameSite cookies for that.
Simple requests and preflighted requests
- Simple requests are GET, HEAD, or POST with only CORS-safelisted headers and a content type of
text/plain,multipart/form-data, orapplication/x-www-form-urlencoded. The browser sends them immediately and lets your code read the response only if the CORS headers allow it. - Preflighted requests are everything else: PUT, DELETE, PATCH, POST with a JSON content type, or any request with a custom header such as
Authorization. The browser first sends an OPTIONS request asking whether the real request is allowed, and sends the real one only if the answer is yes.
The preflight is invisible to your code. You call fetch(), and the browser sends the OPTIONS request by itself. Read the console error closely, because it usually says which one failed: Chrome, for example, says "Response to preflight request doesn't pass access control check" when the OPTIONS request is the problem.
The headers that matter
Set by the browser:
Origin: https://app.example.com: where the request comes from.Access-Control-Request-Method: PUT(preflight only): the method of the real request.Access-Control-Request-Headers: x-custom-header(preflight only): the non-safelisted headers it will send.
Set by your server:
Access-Control-Allow-Origin: the permitted origin. It must be the exact origin, not*, when credentials are involved.Access-Control-Allow-Methods(preflight): permitted methods.Access-Control-Allow-Headers(preflight): permitted request headers.Access-Control-Allow-Credentials: true: required if the request is made with credentials, and cannot be combined withAccess-Control-Allow-Origin: *.Access-Control-Max-Age: 600: how many seconds the browser may cache a successful preflight. Browsers apply their own maximum, for example two hours in Chromium.
The debugging flow
Step 1: find the failing request in DevTools
Open the Network tab and find the failed request. Check whether it is the OPTIONS preflight or the actual GET or POST. If you do not see the OPTIONS row, clear the Fetch/XHR filter and look under All. Check the response headers on whichever one failed.
Step 2: repeat the request with curl
curl does not enforce CORS, so it shows you exactly what the server returns. Add an Origin header to imitate the browser:
# Test the preflight
curl -i -X OPTIONS https://api.example.com/users/42 \
-H "Origin: https://app.example.com" \
-H "Access-Control-Request-Method: PUT" \
-H "Access-Control-Request-Headers: Content-Type"
# Test the actual request
curl -i -X PUT https://api.example.com/users/42 \
-H "Origin: https://app.example.com" \
-H "Content-Type: application/json" \
-d '{"name":"new"}'
If the CORS headers are missing or wrong here, the problem is on the server. If they look right, compare the curl request with the failing request in the Network tab, including cookies and the exact URL, and then check caches and any proxy in front of the API.
Step 3: check the exact value of Access-Control-Allow-Origin
Common mistakes:
- The server returns
http://app.example.combut the page is onhttps://app.example.com. An origin includes the scheme. - The server returns
*but the request includes credentials. The browser rejects this. - The server returns a trailing slash.
https://app.example.com/is not the same ashttps://app.example.com. - The server sends more than one value, or the header twice, often because both the application and a reverse proxy add it. The browser rejects this.
Step 4: rule out caching
Browsers only cache successful preflights, so a failed preflight will be retried. Two kinds of stale data can still mislead you. A cached successful preflight can keep allowing a method or header the server no longer allows, until Access-Control-Max-Age runs out. And a response cached by the browser or a CDN without CORS headers, or with another origin's value, can be served to your page. That second case is why Vary: Origin matters. Checking "Disable cache" in DevTools and reloading rules out the browser's side.
Step 5: check which request the browser actually sent
Confirm the URL and method in the Network tab. A request that accidentally resolves to the same origin, for example through a relative URL, follows the same-origin rules and never needs CORS headers, while the same code pointed at another origin in production does. Same-origin GET requests also do not carry an Origin header, so a server that only adds CORS headers when it sees one will behave differently between the two.
The wildcard problem
Access-Control-Allow-Origin: * is fine for public APIs that do not use credentials. For anything using cookies, it does not work: if a request is made with credentials: 'include' and the server answers with the wildcard, the browser refuses to expose the response to your code.
The usual production pattern is to keep an allowlist of origins on the server, compare the incoming Origin header against it, and echo back the match. Send Vary: Origin on every response from that route, including responses for origins that are not allowed, so caches do not serve one origin's answer to another:
// Express middleware sketch
const ALLOWED = new Set([
'https://app.example.com',
'https://staging.example.com',
]);
app.use((req, res, next) => {
const origin = req.headers.origin;
res.set('Vary', 'Origin');
if (ALLOWED.has(origin)) {
res.set('Access-Control-Allow-Origin', origin);
res.set('Access-Control-Allow-Credentials', 'true');
}
if (req.method === 'OPTIONS') {
res.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH');
res.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
res.set('Access-Control-Max-Age', '600');
return res.sendStatus(204);
}
next();
});
Errors that look like CORS but are something else
- A server or proxy error. If your application crashes and a 500 or 502 comes back from a layer that does not add CORS headers, the browser reports a CORS error. Check the status code in the Network tab first.
- Mixed content. An HTTPS page calling an HTTP endpoint is blocked by the browser before CORS applies. The console gives a separate mixed-content message.
- TLS certificate problems. An invalid certificate makes
fetch()reject with a generic network error, and the console shows something likenet::ERR_CERT_AUTHORITY_INVALID. - Redirects. A preflight that gets a redirect fails. Common causes are a missing trailing slash or an HTTP to HTTPS redirect.
When in doubt, go back to step 2. curl with -i shows whether the server is responding correctly.
Tools on this site
- curl to code turns a working curl command into JavaScript (fetch or axios), Python, PHP, Go, Ruby, Java, or C#. Comparing that output with your application code can expose a missing header.
- API tester sends requests from your browser with custom headers. It is subject to CORS itself, and the origin the API sees is
https://boltquicktools.com, so a failure there is expected if the API does not allow that origin.