Fix a CORS preflight failure

Requests that trigger a preflight

Browsers skip the preflight check only for safelisted requests. A cross-origin request qualifies when it uses GET, HEAD, or a POST with safelisted headers and a content type of application/x-www-form-urlencoded, multipart/form-data, or text/plain.

• HTTP methods outside the safelist, including PUT, DELETE, and PATCH.
• Headers outside the safelist, such as Authorization or X-Api-Key.
• A Content-Type header set to application/json.
• Streaming request bodies created with a ReadableStream.

Standard JSON payloads trigger this probe immediately. Sending an application/json body requires the browser to verify server permissions before transmitting the payload.

Inspect the OPTIONS probe in developer tools

Open the browser developer tools and inspect the Network panel for the failing OPTIONS entry. A passing options preflight returns a 2xx status code alongside Access-Control-Allow-Origin, an Access-Control-Allow-Methods header listing the requested method, and Access-Control-Allow-Headers matching any custom request headers.

> OPTIONS /data HTTP/2
> origin: https://your-site.com
> access-control-request-method: PUT
> access-control-request-headers: x-api-key

< HTTP/2 204
< access-control-allow-origin: https://your-site.com
< access-control-allow-methods: PUT
< access-control-allow-headers: x-api-key
< access-control-max-age: 600

# Any of the four response headers missing or wrong = preflight failed,
# and the browser never sends the PUT.

Browsers drop the subsequent operation whenever this handshake fails. If the probe yields a non-2xx code, the console reports that it does not have HTTP ok status. When headers mismatch, the console states that the response to preflight request doesn't pass access control check, and the real request never leaves the client.

Common causes of preflight failures

Preflight failures stem from server-side routing, authentication policies, or network intermediaries. Inspecting the raw OPTIONS response reveals which condition aborted the exchange.

• Missing OPTIONS handlers return a 404 Not Found or 405 Method Not Allowed response.
• Authentication middleware rejects the probe with 401 or 403 because preflight requests do not carry credentials.
• The Access-Control-Allow-Headers header omits a requested client header like Authorization.
• Redirect responses on OPTIONS calls fail immediately under the Fetch specification.
• Omitting Access-Control-Max-Age leaves only the five-second browser default, so the OPTIONS probe repeats before nearly every request.
• Edge proxies or CDNs strip the outgoing Access-Control-* headers before transmission.

Handle the OPTIONS probe on your server

Configure your backend router to handle OPTIONS requests explicitly by returning an HTTP 204 No Content status. Exempt all OPTIONS routes from authentication middleware so unauthenticated probes succeed. Set Access-Control-Allow-Origin, provide explicit method names in Access-Control-Allow-Methods, and enumerate all custom client headers inside Access-Control-Allow-Headers. Add Access-Control-Max-Age: 86400 to allow browsers to cache the preflight verdict across subsequent calls.

Handling preflight errors on third-party endpoints

Client-side code cannot alter or bypass preflight checks mandated by third-party APIs. For public resources, route requests through cors.dev using GET or HEAD methods to keep the call safelisted and skip the preflight probe. Because the proxy operator can observe traffic routed through it, use this approach for public data only. Test upstream server responses with the header checker to evaluate their CORS configuration.

Good questions.