Why 'Request header field x-auth-token is not allowed by Access-Control-Allow-Headers' fires, and how to configure the server's header allowlist.
Scenario presets
Request — the browser (page) side
Method
Content-Type
Custom header
Access-Control-Request-Headers: content-type, x-auth-token
Response — headers the server sends
Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers
Headers the request needs + common values — click to toggle
Browser processing steps
Page issues a fetch request
Not a simple request — an OPTIONS preflight is required
OPTIONS preflight request sent
OPTIONS /data HTTP/1.1 Origin: https://myapp.example.com Access-Control-Request-Method: POST Access-Control-Request-Headers: content-type, x-auth-token
Server's preflight response arrives
HTTP/1.1 204 No Content Access-Control-Allow-Origin: https://myapp.example.com Access-Control-Allow-Methods: GET, POST, PUT Access-Control-Allow-Headers: content-type
Allow-Origin matches the origin — pass
Request method is in Allow-Methods — pass
A request header is missing from Allow-Headersx-auth-token
No credentials — check skipped
Browser blocks the response and rejects the fetch
Browser console
✕ Access to fetch at 'https://api.example.com/data' from origin 'https://myapp.example.com' has been blocked by CORS policy: Request header field content-type is not allowed by Access-Control-Allow-Headers in preflight response.
(index):1
Change any value and the steps below recompute instantly. Try the 'credentials + *' scenario to see why the wildcard fails.
Custom headers like Authorization or X-Api-Key — and even a JSON Content-Type — ride the preflight's Access-Control-Request-Headers. If the server's Access-Control-Allow-Headers doesn't cover all of them, the browser blocks with 'header field X is not allowed'.
The classic trap isn't casing (header names are case-insensitive) but omission — forgetting that content-type itself must be allowed too. Listing only authorization still fails on a JSON body.
Edit the custom header name and the Allow-Headers list in this simulator — the request-side Access-Control-Request-Headers box shows exactly what the server must cover. CORS Simulator