Debug CORS preflight failures
The browser rejects a response the server is sending, because a required Access-Control-* header is
missing or does not match the request. curl never enforces CORS, so it always "works" and misleads you.
Procedure
- Reproduce the preflight the browser actually sends — the
OPTIONSrequest with the origin and the method it intends to use:curl -si -X OPTIONS https://api.example.com/v1/items \ -H 'Origin: https://app.example.com' \ -H 'Access-Control-Request-Method: PUT' \ -H 'Access-Control-Request-Headers: content-type,authorization' - Check the response for the three headers the browser needs:
A missingAccess-Control-Allow-Origin: https://app.example.com Access-Control-Allow-Methods: PUT, POST, GET Access-Control-Allow-Headers: content-type, authorizationAllow-Methodsthat listsPUT, or anAllow-Headersthat omitsauthorization, is the failure. - Confirm the status is
2xx— a405/404on the OPTIONS route means the framework rejected the preflight before CORS middleware ran. - If credentials are used, verify the exact pair (both required):
Access-Control-Allow-Credentials: true Access-Control-Allow-Origin: https://app.example.com # must NOT be "*"Allow-Origin: *with credentials is rejected outright by the spec. - Confirm the real request's headers too; a preflight that passes can still fail if the actual
response omits
Allow-Origin:curl -si -X PUT https://api.example.com/v1/items \ -H 'Origin: https://app.example.com' -H 'Content-Type: application/json' -d '{}' \ | grep -i '^access-control' - For a wildcard subdomain requirement, echo the request Origin from an allowlist and add
Vary: Originso caches do not serve one origin's headers to another:add_header Vary Origin always; - Cache preflight responses with
Access-Control-Max-Ageto cut the extra round trip:Access-Control-Max-Age: 600
Pitfalls
- Testing with curl
-H 'Origin: ...'without theOPTIONS+Access-Control-Request-Methodpair does not exercise preflight logic. Allow-Origin: *cannot be combined withAllow-Credentials: true; browsers reject it silently.- A proxy stripping
Access-Control-*headers on the way out undoes a correct app config. - CORS must be set on the response to the preflight and the actual request, not only one.
Allow-MethodsomittingOPTIONSor the app returning405to preflight breaks everything.- A redirect (301 to a canonical host) on the preflight is followed by some browsers and fails on others.
- Without
Vary: Origin, a shared CDN cache can return one origin's CORS headers to a different origin.
Verification
curl -si -X OPTIONS https://api.example.com/v1/items \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: PUT' \
-H 'Access-Control-Request-Headers: authorization' | grep -i '^access-control'
Pass means the preflight returns 200 with Allow-Origin echoing the origin (or the allowlisted
value), Allow-Methods including PUT, and Allow-Headers including authorization. Report those
exact headers.