CORS Explained: Why Your Fetch Request Is Blocked
CORS is a browser rule, not a server one. Learn the preflight, the headers, the credentials, and how to fix the common errors.
By Velloreth
What CORS is
CORS is a browser rule.
The browser sends the request, and then checks whether the response is allowed to be read by the page’s origin.
The server declares the policy with a response header.
The browser enforces it. A request from curl, a server, or a mobile app is never blocked, because those clients do not implement CORS.
This is why a request that works in Postman fails in the browser. The server is fine; the browser is refusing to hand the response to the script.
The same-origin policy
An origin is a scheme, a host, and a port.
https://example.com:443
│ │ │
scheme host port
Two URLs are the same origin only if all three match.
https://example.comandhttps://api.example.comare different origins.http://example.comandhttps://example.comare different origins.https://example.comandhttps://example.com:8443are different origins.
The same-origin policy prevents a script on one origin from reading a response from another, which is what stops a malicious page from reading your bank’s API.
CORS is the controlled exception.
A simple request
A simple request is sent directly, with no preflight.
The conditions:
- The method is
GET,HEAD, orPOST. - The content type is
application/x-www-form-urlencoded,multipart/form-data, ortext/plain. - No custom header is set.
The server responds with:
Access-Control-Allow-Origin: https://app.example.com
The browser then allows the script to read the response.
Without the header, the browser blocks the read, and the console shows a CORS error. The request still reached the server, which is an important detail: a CORS failure is not a failure to send.
The preflight
A non-simple request triggers a preflight.
OPTIONS /api/orders HTTP/1.1
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type, authorization
The server answers:
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: content-type, authorization
Access-Control-Max-Age: 86400
The browser then sends the real request.
Access-Control-Max-Age caches the preflight, so it is not repeated for every request. Without it, a preflight is sent before each one, which doubles the latency.
A custom header triggers a preflight. Setting Authorization or Content-Type: application/json is enough, which is why almost every API call from a browser is preflighted.
The headers
| Header | Direction | Meaning |
|---|---|---|
Origin | Request | The page’s origin |
Access-Control-Request-Method | Request | The method the real request will use |
Access-Control-Request-Headers | Request | The headers the real request will set |
Access-Control-Allow-Origin | Response | Which origin may read the response |
Access-Control-Allow-Methods | Response | Which methods are allowed |
Access-Control-Allow-Headers | Response | Which headers are allowed |
Access-Control-Allow-Credentials | Response | Whether a cookie may be sent |
Access-Control-Expose-Headers | Response | Which response headers the script may read |
Access-Control-Max-Age | Response | How long to cache the preflight |
Access-Control-Allow-Origin must be an exact origin or *. It cannot be a list, and it cannot be a pattern. A server that needs to allow several origins must echo the matching one.
Access-Control-Expose-Headers is needed to read a custom response header. By default, a script can read only a small set, and a custom header such as X-Request-Id is invisible without it.
Credentials
A request with a cookie, a client certificate, or an Authorization header is credentialed.
fetch('https://api.example.com/me', {
credentials: 'include',
});
The server must respond with:
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
A wildcard origin is not allowed with credentials. The server must echo the exact origin, which is why a credentialed CORS setup needs a check against an allow-list.
The Vary: Origin header is required when the server echoes the origin, or a shared cache may serve one origin’s response to another.
Common errors
“No ‘Access-Control-Allow-Origin’ header is present.” The server did not send the header, or it sent it only on the real response and not on the preflight.
“The ‘Access-Control-Allow-Origin’ header has a value that is not equal to the supplied origin.” The server sent a different origin, or a wildcard with credentials.
“Request header field authorization is not allowed.” The preflight response is missing Access-Control-Allow-Headers.
“Method PUT is not allowed.” The preflight response is missing Access-Control-Allow-Methods.
“The preflight request did not succeed.” The OPTIONS route returned a 404 or a 500, so the browser never got a policy.
The fix for the last one is to handle OPTIONS explicitly, and to return a 204 with the headers before the authentication middleware runs.
CORS in a development setup
A CORS problem is most common during development, when the front end runs on one port and the API on another, and the two are different origins even though they are on the same machine. The three ways to handle it are a proxy, a permissive development policy, and a same-origin setup. A proxy is the cleanest: the development server forwards a request under its own origin, so the browser sees a same-origin request and CORS never applies. A permissive policy is the quickest: allow the development origin explicitly, and make sure the policy is not the one that ships to production. A same-origin setup is the most faithful: serve the front end from the API in development, so the environment matches production. The mistake to avoid is a wildcard origin in production, because it lets any site read the response, and it is a common leftover from a development shortcut.
Practical guidance
- Remember CORS is a browser rule.
- Handle the
OPTIONSroute explicitly. - Echo the exact origin when credentials are used.
- Add
Vary: Originwhen echoing. - Set
Access-Control-Max-Ageto cache the preflight. - Add
Access-Control-Expose-Headersfor a custom response header. - Do not use a wildcard with credentials.
- Check the preflight response, not only the real one.
- Use a proxy for a third-party API that does not support CORS.
For the related guides, see cookies-explained and csrf-explained. For the broader context, content-security-policy-guide and fetch-api-guide.
Quotable summary
CORS is enforced by the browser rather than the server, so a request from curl is never blocked, which is why a request that works in Postman can fail in the browser. A simple request is sent directly while a request with a custom header or a non-simple method triggers a preflight, which is an OPTIONS request that asks the server which origins and methods are allowed. Access-Control-Allow-Origin must be an exact origin or a wildcard and it cannot be a list, and a credentialed request cannot use a wildcard origin because that would let any site read a credentialed response. A CORS failure is not a failure to send, because the request reached the server and the browser refused to hand the response to the script.