CORS errors usually mean the browser sent a request that the server did not explicitly permit. This guide gives you a repeatable checklist for separating preflight failures, missing response headers, credentials issues, redirects, private-network requests, and CDN or reverse-proxy configuration problems.
Overview
Cross-Origin Resource Sharing, or CORS, is a browser security mechanism. A page loaded from one origin may request a resource from another origin, but the browser checks whether the destination has granted permission. An origin is the combination of scheme, host, and port, so https://app.example.com, http://app.example.com, and https://api.example.com are different origins.
The server grants access with response headers such as Access-Control-Allow-Origin. For some requests, the browser first sends an OPTIONS preflight request describing the intended method and headers. The server must answer that preflight correctly before the browser sends the actual request.
A useful mental model is:
- The browser sends a request, or sends an
OPTIONSpreflight first. - The server, application, CDN, or reverse proxy returns a response.
- The browser checks the CORS headers before exposing the response to JavaScript.
CORS is enforced by browsers. A successful request made with curl or a backend HTTP client does not prove that browser JavaScript will be allowed to read the response. For a broader request-inspection workflow, see the Chrome DevTools Network Tab Guide.
Checklist by scenario
Scenario 1: The request has no preflight
Start by opening DevTools, selecting the request in the Network panel, and checking the Request URL, request method, request headers, status, and response headers. If the request is a simple cross-origin request, the browser may send it directly. The response still needs an appropriate Access-Control-Allow-Origin value before JavaScript can read it.
The value must match the requesting origin, including scheme and port. For example:
Access-Control-Allow-Origin: https://app.example.com
For a public, non-credentialed endpoint, a wildcard may be appropriate:
Access-Control-Allow-Origin: *
Do not treat the wildcard as a general solution. It cannot be combined with credentialed browser requests.
Scenario 2: The browser sends an OPTIONS preflight
A preflight commonly occurs when the request uses a method such as PUT, PATCH, or DELETE, or includes non-safelisted request headers such as a custom header or an authorization header. In DevTools, inspect the OPTIONS request separately from the later application request.
A typical preflight contains headers like these:
OPTIONS /v1/profile HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: PATCH
Access-Control-Request-Headers: authorization, content-type
The response needs to allow the origin, method, and requested headers:
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, PATCH, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Vary: Origin
The exact status is less important than returning a successful response that reaches the browser with the required headers. Confirm that authentication middleware, routing rules, and access controls do not reject OPTIONS before CORS handling runs.
Scenario 3: Credentials are involved
Credentials include cookies and other browser-managed authentication information. If the frontend deliberately sends credentials, it must opt in, for example with fetch:
fetch('https://api.example.com/account', {
credentials: 'include'
});
The server must then return an explicit origin and:
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
Vary: Origin
This combination is invalid for credentialed access:
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Also check cookie attributes and domain rules separately. A correct CORS response does not guarantee that a cookie will be sent or accepted.
Scenario 4: The browser reports a wildcard or origin mismatch
Compare the browser's Origin request header with the server's Access-Control-Allow-Origin response header. Watch for a changed port, an http versus https mismatch, a trailing slash, or a staging hostname being absent from the allowlist. The header contains an origin, not a full URL with a path.
If the server dynamically reflects approved origins, keep the allowlist explicit and add Vary: Origin so a cache does not reuse one origin's response for another.
Scenario 5: Redirects appear in the request chain
Inspect every response in the Network panel, including redirects from HTTP to HTTPS, a bare hostname to a canonical hostname, or an API route to an authentication page. The final response and any relevant redirect response must be compatible with the browser's CORS processing. Avoid relying on a redirect as part of a preflight path; expose the final API endpoint directly where possible.
Scenario 6: A private-network request is blocked
When a public page attempts to reach a service on a more-private network, the browser may perform an additional permission check. If DevTools shows a private-network access failure, inspect the preflight request and the browser's requested headers. The server may need to return an explicitly enabled private-network response header, subject to the browser and deployment environment in use. Treat this as a separate compatibility check rather than adding broad CORS permissions to every endpoint.
Scenario 7: The application works locally but fails behind a proxy or CDN
Test the deployed hostname, not only the application process. A reverse proxy or CDN may answer OPTIONS itself, remove headers, cache an outdated response, or route the preflight to a different origin. Confirm that CORS headers are present on successful responses and relevant error responses, and that the proxy forwards the Origin, Access-Control-Request-Method, and Access-Control-Request-Headers request headers.
A framework-level configuration might look like this in Express:
import cors from 'cors';
app.use(cors({
origin: ['https://app.example.com'],
methods: ['GET', 'POST', 'PATCH', 'DELETE', 'OPTIONS'],
allowedHeaders: ['Content-Type', 'Authorization'],
credentials: true
}));
For an Nginx-style deployment, apply equivalent headers at the layer that actually handles the request, and ensure OPTIONS is not blocked before those headers are added:
add_header Access-Control-Allow-Origin "https://app.example.com" always;
add_header Access-Control-Allow-Methods "GET, POST, PATCH, OPTIONS" always;
add_header Access-Control-Allow-Headers "Content-Type, Authorization" always;
if ($request_method = OPTIONS) {
return 204;
}
Adapt examples to your framework and proxy. Do not copy a permissive development configuration into production without reviewing its origin and credential behavior.
Browser versus curl
| Test | What it tells you | What it does not prove |
|---|---|---|
| Browser fetch | Whether browser CORS policy allows JavaScript to read the response | Whether a backend client can call the API |
| curl with Origin | Which CORS headers the server returns for a chosen origin | How the browser will handle every redirect or credential rule |
| curl OPTIONS | Whether the preflight route responds to the requested method and headers | Whether the frontend uses the same URL, headers, and credentials |
Example preflight test:
curl -i -X OPTIONS 'https://api.example.com/v1/profile' \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: PATCH' \
-H 'Access-Control-Request-Headers: authorization, content-type'
What to double-check
- Origin: Is the exact frontend scheme, host, and port allowed?
- Methods: Does
Access-Control-Allow-Methodsinclude the actual method? - Headers: Does it include every requested non-safelisted header, with spelling checked?
- Credentials: Are the frontend option, server header, and cookie settings consistent?
- Errors: Do authentication, validation, rate-limit, and server-error responses include the headers your frontend needs to diagnose the failure?
- Caching: Is
Vary: Originpresent when responses differ by origin? - Routing: Does the preflight reach the intended service rather than a login page, static server, or CDN edge rule?
- Environment: Are local, staging, and production origins configured separately?
Keep a small environment matrix in the repository or deployment documentation. Record each frontend origin, API origin, credential requirement, allowed methods, and proxy or CDN behavior. This makes a new deployment easier to compare with the last known-good configuration. For related API tooling and request replay options, see Best API Testing Tools for Developers.
Common mistakes
- Adding CORS headers only in the frontend: The browser permission is granted by the destination response, not by JavaScript.
- Using
*with credentials: Use a specific approved origin for credentialed requests. - Testing only with curl: Command-line success does not bypass browser enforcement in a real frontend.
- Allowing methods but not headers: A preflight can fail because
AuthorizationorContent-Typeis missing even when the method is allowed. - Ignoring the OPTIONS route: Authentication or CSRF middleware may reject the preflight before CORS handling runs.
- Changing several layers at once: Identify whether the application, reverse proxy, CDN, or cache produced the response before editing configuration.
- Allowing every origin in production: Limit origins to the environments and applications that genuinely need access.
When to revisit
Review this checklist whenever a frontend connects to a new API, a domain or port changes, authentication is introduced, or a request begins failing only after deployment. Recheck it after changing a reverse proxy, CDN rule, API gateway, framework middleware, or cache policy. It is also worth revisiting before a seasonal release or other major planning cycle if infrastructure and environment settings are being updated.
For a practical final pass, reproduce the failing request in the browser, capture the preflight and actual response, run the matching curl test, and compare the deployed headers with your environment matrix. Change one layer at a time, clear or invalidate relevant caches, and retest both an approved origin and an intentionally unapproved origin. If the problem is broader than CORS, check related TLS and deployment behavior with the SSL Certificate Errors guide and the web app deployment checklist.