VPS Tutorials
CORS errors on Nginx: preflight, response headers and cookie login
Identify failed OPTIONS or real requests, assign one CORS owner, allow an exact frontend origin and verify error responses, credentials and browser login.

An API returns JSON to curl, but the browser reports blocked by CORS policy. Start in Network: determine whether OPTIONS or the following real request failed, then inspect the response headers. Changing servers or adding wildcard headers does not identify the failing layer.
This guide covers a frontend at https://app.example.com and an API at https://api.example.com. The example permits one explicit origin. Replace domains, paths and backend ports for your deployment.
MDN's CORS guide describes the browser's control over scripts reading cross-origin responses. A different scheme, hostname or port can make an origin different, including subdomains under the same parent domain.
curl receiving a response does not prove that browser JavaScript can read it. Likewise, a 502, certificate failure or unreachable server requires fixing that underlying error; CORS headers alone are insufficient.
| Browser symptom | Check first | Responsible layer |
|---|---|---|
| OPTIONS returns 401/403 | Authentication or WAF blocks preflight | Gateway or authentication middleware |
| OPTIONS returns 301/302 | HTTPS, trailing-slash or login redirect | Request URL and proxy rules |
| Allow-Origin missing | The responding layer lacks the header | Application, Nginx or CDN |
| Multiple Allow-Origin values | Two layers add it | Choose one owner |
| Cookie requests fail | Wildcard origin or credentials settings | Frontend and server |
| Only API errors look like CORS failures | Error response lacks headers | Error handling and header rules |
Record Request URL, Origin, status and response headers. Redact Cookie and Authorization before sharing. Keep server authentication and CSRF protection: CORS does not prevent a direct curl call.
JSON POST or Authorization commonly triggers preflight. The browser asks whether the origin, method and headers are allowed before sending the real request; see MDN's preflight reference. Simulate it privately:
curl -i -X OPTIONS 'https://api.example.com/api/profile' \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: POST' \
-H 'Access-Control-Request-Headers: authorization,content-type'
No real token or Cookie is needed for this example. Check:
Access-Control-Allow-Originmatches the complete frontend origin.Access-Control-Allow-Methodsincludes POST.Access-Control-Allow-Headersincludes the real request's headers.
204 is common, but success status is insufficient without matching headers. A longer timeout does not solve 403, and adding Allow: OPTIONS alone does not grant CORS permission. Check the real POST response too.
If the URL redirects to HTTP, login or another hostname, have the frontend request the final API URL directly. See redirect-loop troubleshooting.
Choose who owns CORS. If your framework already has middleware, use that and remove duplicate headers from Nginx, panels and CDN. The alternative below makes Nginx responsible for /api/, while the backend retains authentication.
Merge the location into the API domain's existing HTTPS server. Keep certificates and unrelated settings. The backend is assumed to listen on 127.0.0.1:3000 and require the /api/ path:
location /api/ {
proxy_hide_header Access-Control-Allow-Origin;
proxy_hide_header Access-Control-Allow-Methods;
proxy_hide_header Access-Control-Allow-Headers;
proxy_hide_header Access-Control-Allow-Credentials;
add_header Access-Control-Allow-Origin "https://app.example.com" always;
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
if ($request_method = OPTIONS) {
return 204;
}
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://127.0.0.1:3000;
}
Observe these boundaries:
- An origin has no path or trailing slash. Development
http://localhost:5173is a different origin; see origin mismatch. - List only needed methods and headers. Add PATCH, DELETE or custom headers when the application needs them. This does not replace backend authorization or method validation.
- Nginx answers OPTIONS here while forwarding normal requests. If OPTIONS also serves application functionality, let the application distinguish those requests.
proxy_passhas no trailing slash and preserves/api/. Do not change path mapping while fixing CORS.
The Nginx header reference explains always, which adds headers to relevant error responses too. Otherwise a real 401 or 500 may appear unreadable to browser JavaScript.
Check add_header inheritance: defining headers at this location can affect security headers inherited from a higher level. Inspect final responses. proxy_hide_header removes upstream headers in this Nginx-owned example; do not copy that removal when the application owns CORS.
Check syntax before loading:
sudo nginx -t
sudo systemctl reload nginx
An earlier CDN, WAF or authentication gateway can still reject OPTIONS before Nginx sees it. Permit valid preflight only for the intended business paths, while authenticating real requests.
Cross-origin requests using cookies typically need explicit credentials mode:
fetch("https://api.example.com/api/profile", {
credentials: "include"
});
The server needs an explicit allowed origin and Access-Control-Allow-Credentials: true. In the Nginx-owned scheme, add this alongside the other add_header directives in the same location:
add_header Access-Control-Allow-Credentials "true" always;
Credentialed requests cannot use Access-Control-Allow-Origin: *; see MDN's credentials/wildcard explanation. Do not enable credentials on every API when they are unnecessary.
Actual cookie delivery also depends on Domain, Path, Secure, SameSite and third-party-cookie policy. Cross-origin does not always mean cross-site: two subdomains do not automatically require SameSite=None. Truly cross-site cookies involve Secure and browser restrictions. If login still fails after CORS is correct, investigate cookies and sessions rather than broadening allowed origins.
Do not use mode: "no-cors" to read a cross-origin API. It produces an opaque response whose status and JSON cannot be read normally; see Fetch guidance.
Do not reflect arbitrary Origin values while permitting credentials. Multiple trusted frontends need an exact allowlist. When selecting an origin dynamically, configure Vary: Origin so caches separate responses by origin.
Do not add Allow-Origin independently in the application, Nginx and CDN. Duplicate headers or a comma-separated origin list are not a multiple-origin permission mechanism; see MDN's duplicate-header error. Check the final response, not only the configuration file.
Test an allowed origin's OPTIONS and real request, then a disallowed origin. With this fixed-origin configuration, disallowed preflight can still return 204, but Allow-Origin does not match and the browser does not permit reading. This is not a server-side 403 policy.
Check an unauthenticated response and a controlled error response for exactly one CORS header set. Then verify real browser login and the business action. curl observes headers without applying browser CORS, cookie or cache policies.
The original article reports eight local request combinations using Nginx 1.19.6 and a mock backend on loopback. Allowed OPTIONS returned 204, GET/POST 200; mock 401 and 500 responses retained one Allow-Origin. Disallowed origins did not match the fixed value. Adding credentials produced true on OPTIONS and GET. OPTIONS never reached the mock backend. These were HTTP header checks, without production TLS, a real session or browser-enforcement validation.
For FastAPI, see deployment and CORS considerations. Identify the failing request and one layer responsible for headers before changing the rule.