Why Preflight Requests Use the OPTIONS Method

When a cross-origin fetch() call fails with a message about a preflight check, the browser has already sent an OPTIONS request that your server did not handle correctly. This page explains why OPTIONS is the mandated method for that probe, what the server must return, and how to verify the fix.

This page is part of Simple vs Preflight Requests: CORS Mechanics, which covers the full classification logic that determines whether a browser sends a preflight at all.

The Exact Error This Page Resolves

Access to fetch at 'https://api.service.internal/data' from origin
'https://app.client.internal' has been blocked by CORS policy:
Response to preflight request doesn't pass access control check:
No 'Access-Control-Allow-Origin' header is present on the requested resource.

This error appears in the browser console when the OPTIONS preflight response is missing one or more required CORS headers — or when the server returns a non-2xx status for OPTIONS entirely.

Root Cause

The WHATWG Fetch Standard (section 4.8) requires browsers to send a preflight OPTIONS request before any cross-origin request that is not classified as “simple.” The browser chose OPTIONS specifically because RFC 9110 (which obsoletes RFC 7231) designates it as safe (no server state modification) and idempotent (repeated calls produce the same result). Using GET or POST for the probe would risk triggering business logic or creating resources before any permission check has been granted.

The server must respond with explicit Access-Control-Allow-* headers on the OPTIONS response. If it does not — or if a WAF, reverse proxy, or missing route handler drops the request — the browser blocks the actual request entirely and surfaces the error above.

RFC 9110 draws two lines that leave OPTIONS as the only workable candidate. Section 9.2.1 defines a safe method as one whose semantics are read-only, and section 9.2.2 defines an idempotent method as one where several identical requests have the same effect on the server as a single one. OPTIONS satisfies both, and section 9.3.7 additionally defines it as a request for information about the communication options available for a resource — which is exactly the question a preflight asks. GET and HEAD are also safe and idempotent, but they are already the methods a simple request uses, so neither the server nor any cache, access log, rate limiter, or analytics pipeline in the path could distinguish a permission probe from a genuine read; every cross-origin call would be counted twice. POST, PUT, and PATCH are neither safe nor idempotent, so a probe using them could create or mutate a record before permission had been granted. Inventing a new verb would be worse still: a non-standard method is itself never simple, so the probe would need its own preflight, and intermediaries that answer unrecognised verbs with 501 Not Implemented would break the handshake before it started.

One consequence of that design catches teams out repeatedly. The preflight is composed by the browser, not by your code, and the Fetch Standard specifies that it is sent with the credentials mode set to omit: no cookies, no Authorization header, no client certificate. A server that routes OPTIONS through its authentication filter will therefore reject its own preflight with 401 or 403, and the actual request is never attempted. The OPTIONS handler has to sit in front of authentication, not behind it.

What the Browser Sends in the Probe

The preflight is not a generic capability query. It is a narrow, three-part question about a request that has not happened yet, and each part expects one specific header in reply. The browser sets Origin to the serialized origin of the requesting page, Access-Control-Request-Method to the method the real request will use, and — only when the real request will carry headers outside the CORS-safelist — Access-Control-Request-Headers to a comma-separated list of those header names, lowercased and byte-sorted. There is never a request body, so Content-Length: 0 on the probe is normal rather than a sign of truncation.

Lining the two header sets up side by side makes the pairing obvious:

Two details in that pairing trip up hand-written handlers. First, the browser matches Access-Control-Request-Headers against Access-Control-Allow-Headers case-insensitively but name for name, so a handler that echoes back only the header names it happens to recognise will silently omit something like x-request-id and fail the check. Second, Access-Control-Allow-Methods is evaluated as a complete list rather than a single answer: returning only the verb that was asked about is legal, but it forces a fresh preflight for every distinct method, whereas listing the endpoint’s full verb set once lets a single cached result cover them all.

Prerequisite State

Before applying the fix below, confirm:

• Your server framework has a route or middleware layer that can match OPTIONS requests on the relevant path.
• No upstream WAF rule blocks OPTIONS traffic (common with security profiles that treat OPTIONS as a reconnaissance method).
• The Access-Control-Allow-Origin domain list on the server matches the exact origin (scheme + host + port) the browser sends.

Step-by-Step Fix

1. Add an explicit OPTIONS handler (Express.js)

app.options('/data', (req, res) => {
  const allowedOrigins = ['https://app.client.internal'];
  const origin = req.headers.origin;
  if (allowedOrigins.includes(origin)) {
    res.setHeader('Access-Control-Allow-Origin', origin);
    res.setHeader('Vary', 'Origin');
  }
  res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-Custom-Header');
  res.setHeader('Access-Control-Max-Age', '600');
  res.sendStatus(204);
});

2. Use the cors middleware for all routes (Express.js shorthand)

const cors = require('cors');

const corsOptions = {
  origin: ['https://app.client.internal'],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'X-Custom-Header'],
  maxAge: 600,
};

app.use(cors(corsOptions));
app.options('*', cors(corsOptions)); // handle preflight for all routes

3. Nginx — intercept OPTIONS at the edge

location /api/ {
  if ($request_method = 'OPTIONS') {
    add_header 'Access-Control-Allow-Origin' '$http_origin';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS';
    add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-Custom-Header';
    add_header 'Vary' 'Origin';
    add_header 'Access-Control-Max-Age' '600';
    return 204;
  }
  proxy_pass http://backend_upstream;
}

4. Apache — respond to OPTIONS before backend logic runs

  Header set Access-Control-Allow-Origin "%{HTTP_ORIGIN}e" env=HTTP_ORIGIN
  Header set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
  Header set Access-Control-Allow-Headers "Authorization, Content-Type, X-Custom-Header"
  Header set Access-Control-Max-Age "600"
  Header set Vary "Origin"
  Header set Content-Length "0"
  Header set Content-Type "text/plain"
  RewriteRule .* - [R=204,L]

5. Clear the framework traps that swallow the OPTIONS request

Each of the four snippets above assumes the request actually reaches the handler you wrote. Several widely used stacks break that assumption in ways that produce the same console error:

• Express 5 upgraded to path-to-regexp v8, which no longer accepts a bare * as a route path. The familiar app.options('*', cors(corsOptions)) line now throws at startup, and a process that crashes on boot answers nothing at all. Use a named wildcard, or simply let the cors() middleware handle preflight for every route.
• Nginx discards every inherited add_header directive as soon as an inner block declares one of its own, and it does not apply add_header to non-2xx responses unless you append always. A preflight that hits an error page therefore arrives header-less.
• Apache behaves the same way: Header set only touches successful responses, so Header always set is the correct form for a CORS header that must survive a 403.
• Spring Security runs its filter chain before Spring MVC’s CORS handling, so a preflight is rejected by the authorization filter unless http.cors(Customizer.withDefaults()) inserts CorsFilter early in the chain.
• Django requires corsheaders.middleware.CorsMiddleware to be listed above django.middleware.common.CommonMiddleware in MIDDLEWARE, otherwise the common middleware’s APPEND_SLASH redirect answers the probe first.

// Express 5: a bare '*' is no longer a valid route path.
app.use(cors(corsOptions));
app.options('/{*splat}', cors(corsOptions));

# Nginx: without `always` these headers are dropped on 4xx and 5xx responses.
location /api/ {
  add_header 'Access-Control-Allow-Origin' '$http_origin' always;
  add_header 'Vary' 'Origin' always;
  proxy_pass http://backend_upstream;
}

Verification

Run this curl command to simulate the exact preflight the browser sends:

curl -si -X OPTIONS https://api.service.internal/data \
  -H 'Origin: https://app.client.internal' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: X-Custom-Header'

Check for all of the following in the response:

• Status line is HTTP/1.1 204 No Content or HTTP/1.1 200 OK
• Access-Control-Allow-Origin matches the Origin header you sent
• Access-Control-Allow-Methods includes POST (or whichever verb your app uses)
• Access-Control-Allow-Headers includes X-Custom-Header
• Vary: Origin is present
• Access-Control-Max-Age is set (optional but recommended)

In DevTools, open the Network tab, enable Preserve log, reproduce the failing request, and filter by Fetch/XHR. You should see a separate OPTIONS row with a 204 or 200 status appearing immediately before your actual request row.

Not every 2xx passes, and not every failure looks different in the console. The Fetch Standard treats the preflight response as a permission grant only when the status is an ok status and the origin check on that same response succeeds; a redirect is rejected outright, because following it would let the server move the probe to a resource the browser never asked about. Four outcomes cover almost everything you will see:

The redirect row hides best of the four. A framework that normalises URLs by appending a trailing slash will happily redirect OPTIONS /data to OPTIONS /data/, and because the browser refuses to follow it the console prints the same generic wording as a missing header. Requesting the canonical URL from the client, or excluding OPTIONS from the redirect rule, removes that whole class of failure without touching your CORS configuration.

Security Boundary Note

Do not set Access-Control-Allow-Origin: * on endpoints that accept cookies or Authorization headers. The Fetch Standard prohibits credentials with wildcard origins — the browser will block the credentialed request even if the preflight passes. Reflect the exact validated origin using dynamic origin validation patterns instead, and always pair it with Vary: Origin to prevent CDN cache poisoning across different requesting domains (see handling the Vary: Origin header correctly for the full explanation).

Common Mistakes

FAQ