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 requestOrigin, or be*when credentials are off.Access-Control-Allow-Methods(ACAM) — must list the method you intend (e.g.POST), not onlyGET.Access-Control-Allow-Headers(ACAH) — must list custom headers the app sends (Authorization,Content-Typewith a non-simple value,X-*).Access-Control-Allow-Credentials: true— only when cookies orAuthorizationmust 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
Authorizationor 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:3000vshttp://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.