CORS and Preflight: A Step-by-Step Debugging Guide

By BoltQuickTools team · May 18, 2026 · Updated November 8, 2026 · 7 min read

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

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:

Set by your server:

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:

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

When in doubt, go back to step 2. curl with -i shows whether the server is responding correctly.

Tools on this site

Related