CORS preflight request (OPTIONS), tested

A preflight request is an OPTIONS request the browser sends before a cross-origin request that is not "simple". It asks the server: may this origin use this method and these headers? Only if the answer is yes does the real request go out. We ran 23 kinds of fetch and XHR calls in Chromium 153 and counted what reached the server.

1. Our test setup

The page was served from http://localhost:8992. The API ran on http://localhost:8993. Different port means a different origin, so every call was cross-origin. A cookie sid=abc was set for localhost.

The API logged method, Access-Control-Request-* headers and Cookie for each request. Its OPTIONS answer allowed everything: it echoed the Origin, set Access-Control-Allow-Credentials: true, allowed GET, POST, PUT, DELETE, PATCH and echoed the requested headers. So every request below succeeded, and we only counted preflights.

2. Which requests trigger a preflight

The rule that fits every row: a request is "simple" only if the method is GET, HEAD or POST, every header you add is on the safelist (Accept, Accept-Language, Content-Language, Content-Type and a single-range Range), and Content-Type is one of text/plain, application/x-www-form-urlencoded or multipart/form-data. Anything else is preflighted. Credentials alone do not cause a preflight.

Two surprises. A JSON Blob triggers a preflight even if you never set a header, because the browser copies the Blob type into Content-Type. And an XHR upload progress listener alone turns a simple POST into a preflighted one.

The streaming body did get its preflight, but then the request failed with TypeError: Failed to fetch and the console showed net::ERR_ALPN_NEGOTIATION_FAILED. Chromium only sends streaming uploads over HTTP/2 or later, and our test API spoke plain HTTP/1.1.

3. What the OPTIONS request carries

OPTIONS /api HTTP/1.1
Origin: http://localhost:8992
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: authorization,content-type,x-alpha,x-zeta
Accept: */*
Sec-Fetch-Mode: cors

• Access-Control-Request-Method was always there, even for POST.
• Access-Control-Request-Headers was only there when there were non-safelisted headers. Chromium sent the names lowercase, sorted, comma-separated with no spaces. We set X-Zeta, Content-Type, X-Alpha, Authorization in that order and got authorization,content-type,x-alpha,x-zeta.
• No cookies, ever. Even with credentials: 'include', the OPTIONS had no Cookie header. The real PUT that followed had sid=abc. So never put auth checks on OPTIONS. A preflight with an Authorization header does not carry the token either. It only lists the header name.
• No request body.

The Origin header is explained in Origin header. Sec-Fetch-Mode: cors is covered in Sec-Fetch-Site, Mode and Dest.

4. What the server must answer

The preflight answer needs a 2xx status and the right Access-Control-Allow-* headers. We tried other statuses with the same headers:

In every blocked case the real request never reached the server, and fetch threw TypeError: Failed to fetch. The full text is in the console. All CORS console messages are listed in CORS error messages explained.

A minimal Node handler:

if (req.method === 'OPTIONS') {
  res.writeHead(204, {
    'Access-Control-Allow-Origin': req.headers.origin,   // check it against a list first
    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH',
    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    'Access-Control-Max-Age': '600',
    'Vary': 'Origin',
  });
  return res.end();
}

Never echo any origin blindly. See CORS: allow multiple origins for an allowlist. The header details are in Access-Control-Allow-Methods, Access-Control-Allow-Headers and Access-Control-Allow-Credentials.

5. Preflight caching and Access-Control-Max-Age

We sent the same JSON PUT twice to the same URL, with a pause between, and counted OPTIONS hits.

So without the header Chromium caches a preflight for 5 seconds. A set value is honoured. 0 disables the cache. Per the Chromium source and MDN docs (not measured, it would take hours), Chromium caps the value at 7200 seconds (2 hours). Firefox's cap is 86400 per its docs.

The cache is narrow. With Max-Age 60 we saw:

• Same URL again: no preflight.
• Different path (/c-y): new preflight.
• Same path with a query string (/c-x?q=1): new preflight. The cache key is the full URL.
• Same URL, a header not in the cached list (X-B after X-A): new preflight.

For APIs with many URLs (/items/1, /items/2...) the cache helps little. Each new URL costs one extra round trip. More on this in Access-Control-Max-Age.

6. How to avoid a preflight

• Serve the API from the same origin, for example behind a /api/ path on the same host. Same-origin requests never preflight (we saw a same-origin PUT with JSON and a custom header go straight through).
• For simple reads, use plain GET with no custom headers. Put tokens in a cookie instead of an Authorization header if your design allows it (see SameSite cookies).
• Sending JSON as text/plain avoids the preflight, but only do it if the server parses it on purpose. It also skips the protection that a preflight gives against cross-site form-style POSTs, so the server must check Origin or a CSRF token.
• Otherwise, set Access-Control-Max-Age so repeat calls to the same URL skip the OPTIONS.

Check what your OPTIONS endpoint really returns with the HTTP headers checker or the PlainHeaders extension.

Written with AI assistance. Measured on 2026-10-02 with headless Chromium 153.0.8010.12 (Playwright) and Node.js 24. The page ran on http://localhost:8992 and the API on http://localhost:8993. A Node server logged every request, so each OPTIONS hit was counted server-side. Items marked as from the docs were not measured. PlainHeaders is our extension; Chromium, Playwright and Node.js are free.