CORS Preflight Debugging with curl -X OPTIONS

How a Browser Initiates a CORS Preflight Request?

When a page runs JavaScript that calls fetch or XMLHttpRequest with a non‑simple method (POST, PUT, DELETE) or a custom header, the browser first sends an OPTIONS request. The request URL is the same as the upcoming call, but the method is OPTIONS. The headers it adds are:

• Origin – the scheme, host, and port of the page making the request.
• Access-Control-Request-Method – the HTTP method of the real request.
• Access-Control-Request-Headers – (optional) the custom headers the real request will send.

The server must reply with at least:

• Access-Control-Allow-Origin – the requesting origin or *.
• Access-Control-Allow-Methods – a list that includes the real method.
• Access-Control-Allow-Headers – a list that includes any custom headers.
• Vary: Origin – tells caches to respect the origin.

If any of these is missing or malformed, the browser aborts the real request and logs a preflight error. The exact error message includes the missing header name, which is the first clue for a developer.

Real‑World Failure Case Study: “Payment Service” Outage

At 02:17 UTC on 2024‑09‑12, a rollout of a new payment API introduced a custom middleware in Node.js v20.12.3 that stripped all CORS headers for security auditing. The following morning, users reported:

Access to XMLHttpRequest at 'https://api.example.dev/checkout' from origin
'https://client.example.com' has been blocked by CORS policy:
Response to preflight request doesn't pass access control check:
It does not have HTTP status code 200 (or 204) and
access-control-allow-origin '*'.

The server logs contained the line:

[error] preflight failed: origin missing – /checkout

Root cause – The middleware removed Access-Control-Allow-Origin and Access-Control-Allow-Methods after the request passed the initial authentication check.

Resolution – Engineers rolled back the middleware, added the required headers in the Express app:

app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', req.headers.origin);
  res.header('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE');
  res.header('Access-Control-Allow-Headers', 'content-type');
  next();
});