Fix CORS preflight failures and Access-Control-Allow-Origin

The browser blocks cross-origin calls when response headers do not match what the spec requires. A failed OPTIONS preflight never reaches your handler; the console blames CORS even when your GET would have worked.

What a preflight is

“Non-simple” cross-origin requests trigger an automatic OPTIONS request first. The browser sends Origin, often Access-Control-Request-Method, and sometimes Access-Control-Request-Headers.

If the OPTIONS response does not allow that origin, method and headers, the browser aborts. Your real POST or PUT is never sent.

Headers that must line up

  • Access-Control-Allow-Origin (ACAO) — must echo the request Origin, or be * when credentials are off.
  • Access-Control-Allow-Methods (ACAM) — must list the method you intend (e.g. POST), not only GET.
  • Access-Control-Allow-Headers (ACAH) — must list custom headers the app sends (Authorization, Content-Type with a non-simple value, X-*).
  • Access-Control-Allow-Credentials: true — only when cookies or Authorization must cross origins; then ACAO cannot be *.
  • Access-Control-Max-Age — optional cache for the preflight; does not replace correct headers.

Credentials and the wildcard rule

If the request carries cookies or you set credentials: "include", the response must use the exact Origin string, not *.

Some stacks default ACAO to * while also setting Access-Control-Allow-Credentials: true. Browsers reject that pair by design.

// Browser expectation with credentials
Access-Control-Allow-Origin: https://app.example
Access-Control-Allow-Credentials: true

// Invalid with cookies / Authorization
Access-Control-Allow-Origin: *

How to use the ToolDeck CORS debugger

Open DevTools → Network → the failed request. Copy request headers from the OPTIONS (or the main call) and the matching response headers.

Paste both blocks into the CORS tool. It runs a yes/no checklist locally. Nothing is fetched; your API URL is never contacted from ToolDeck.

  • A red ACAO row usually means a typo, a missing header on OPTIONS only, or a proxy stripping headers on preflight.
  • A missing ACAM row is common when CORS middleware is wired only for GET.
  • ACAH failures often trace to Authorization or a custom header not listed in the allow-headers response.

Questions

Why do I see CORS on localhost?
Different ports are different origins (http://localhost:3000 vs http://localhost:8080). Allow the dev Origin explicitly or use a dev proxy.
Does a 204 OPTIONS without CORS headers fix it?
No. The OPTIONS response must carry the Allow-* headers. An empty 204 without ACAO still fails.
Can I disable preflight?
Only by making the request “simple” (GET/HEAD/POST with simple headers and content types). Custom JSON APIs usually need a correct OPTIONS response instead.
Postman works but the browser does not — why?
Postman is not a browser CORS enforcement client. Browsers apply the ACAO / ACAM / ACAH rules; curl and server-to-server calls do not.

See also

Related tool: CORS preflight debugger. Runs in your browser; input is not uploaded.