A CORS error means a browser has stopped a web page from reading a response from a different origin. This guide gives you a repeatable way to identify whether the problem is the origin, a preflight request, credentials, redirects, server configuration, or the deployment environment—and then verify the fix safely.
Overview
CORS, or Cross-Origin Resource Sharing, works within the browser’s same-origin security model. An origin is the combination of scheme, host, and port. For example, https://app.example.test and https://api.example.test have different origins even though they share a parent domain. A different port or scheme also creates a different origin.
The browser may send a cross-origin request, but it will only expose the response to JavaScript when the API returns compatible CORS headers. This is why a request can appear in the Network panel while your application receives a message such as Blocked by CORS policy. The server may have responded, but the browser declined to make that response available to the page.
There are two broad request paths:
- Simple requests: The browser sends the request directly, subject to restrictions on methods and headers. The response still needs an appropriate
Access-Control-Allow-Originheader. - Preflighted requests: Before sending the actual request, the browser sends an
OPTIONSrequest to ask whether the method and headers are allowed. The API must answer that request correctly.
Start with the browser’s Network panel, not only the console message. Inspect the request method, status code, request headers, response headers, redirects, and whether the failed entry is OPTIONS or the actual API call. A JSON formatter can help inspect a successful API body, but it will not repair missing CORS headers.
Checklist by scenario
1. Every cross-origin request is blocked
- Copy the exact frontend origin from the address bar, including scheme and port.
- Compare it with the origin configured on the API. Do not assume that a subdomain, development port, or HTTP-to-HTTPS change is equivalent.
- Confirm that the API response includes an
Access-Control-Allow-Originvalue matching the requesting origin. - Check that the CORS middleware runs before routes, authentication failures, and error handlers where your framework requires that order.
- Test an error response as well as a successful response. CORS headers that appear only on successful responses can make debugging misleading.
For a controlled public endpoint, a wildcard may be appropriate in some designs. It is not a substitute for an explicit origin when browser credentials are involved, and it should not be used merely to hide an unknown configuration problem.
2. The CORS preflight request fails
A preflight usually appears as an OPTIONS request. It can be triggered by methods such as PUT, PATCH, or DELETE, or by non-simple request headers such as a custom header or an authorization header.
Check that the preflight response includes the permissions the browser requested:
Access-Control-Allow-Originmatches the frontend origin.Access-Control-Allow-Methodsincludes the intended method.Access-Control-Allow-Headersincludes requested headers such asAuthorizationorContent-Type.- The
OPTIONSrequest is not rejected by authentication, CSRF checks, a router, or a proxy. - The response is not redirected to a login page, a canonical URL, or another host.
You can reproduce the permission check with curl:
curl -i -X OPTIONS https://api.example.test/users \
-H "Origin: https://app.example.test" \
-H "Access-Control-Request-Method: POST" \
-H "Access-Control-Request-Headers: authorization,content-type"
The result should be inspected as HTTP headers, not just as a status code. A successful status without the required CORS headers is still a failed preflight from the browser’s perspective.
3. Requests fail only when credentials are included
Credentials can include cookies, client certificates, or other browser-managed authentication data. If frontend code uses credentials: "include", the API must explicitly allow the requesting origin and return Access-Control-Allow-Credentials: true. The origin cannot be an unrestricted wildcard in this arrangement.
Also verify that the cookie itself is eligible for the request. Review its domain, path, secure setting, and cross-site policy. A CORS fix cannot make an ineligible cookie appear in a request. For token-based authentication, confirm that the authorization header is allowed during preflight and that the token is sent only over an appropriate connection.
4. The API works locally but fails after deployment
Compare the complete deployed origins rather than copying the local configuration. Common differences include a new frontend hostname, a reverse proxy, a TLS terminator, a preview deployment URL, or an API gateway that handles OPTIONS separately.
Check the response at each layer. The application may add CORS headers while a proxy replaces them, or the proxy may return an error before the application runs. If the frontend calls one hostname and that hostname redirects to another, test the final URL and remove the redirect from the API request path where possible.
5. Framework configuration is the suspected cause
In Express, configure a CORS middleware with an explicit allowlist and place it early in the middleware chain. Ensure that the middleware handles OPTIONS requests and that error responses receive the intended headers.
In Django, verify that the CORS package or middleware is installed and ordered according to its documentation. Confirm the allowed origins, allowed methods, and allowed headers, and distinguish between trusted-origin settings used for request protection and settings that control response sharing.
In Laravel, confirm that the CORS configuration covers the API paths being called and that the application or web server is not intercepting OPTIONS. Clear or rebuild configuration caches after changing environment-backed settings when the deployment process requires it.
For serverless functions, configure CORS on every relevant response path, including validation errors and authorization failures. If an API gateway handles preflight, configure it there rather than assuming the function will receive the OPTIONS request.
What to double-check
| Area | What to inspect | Typical correction |
|---|---|---|
| Origin | Scheme, hostname, and port in the browser request | Add the exact development, staging, or production origin to the allowlist |
| Preflight | OPTIONS status and response headers | Allow the requested method and headers without requiring normal authentication |
| Credentials | Fetch mode, cookies, and credential response header | Use an explicit origin and enable credentials consistently on both sides |
| Headers | Requested headers shown in Access-Control-Request-Headers | Allow only the headers the application actually needs |
| Redirects | Location headers and login or canonical-host redirects | Call the final API URL directly or correct the routing and proxy configuration |
| Errors | 401, 403, 404, and 500 responses | Apply the CORS policy to relevant error responses too |
Keep a small request record while debugging: frontend origin, API URL, method, credentials mode, custom headers, preflight result, and actual response status. This prevents a change to one variable from being mistaken for a complete fix.
Common mistakes
- Using a browser extension as the solution: Extensions can change local browser behavior, but they do not fix the production API for other users.
- Adding a permissive wildcard immediately: This can conceal an origin or credential design problem and may be incompatible with credentialed requests.
- Checking only the actual request: If preflight fails, the actual request may never be sent. Inspect both entries.
- Allowing a request header that is not actually supported: The server must be prepared to process the method and header, not merely list them in a response.
- Fixing only the success path: Authentication and validation failures can still appear as CORS failures when their responses omit CORS headers.
- Confusing CORS with server authorization: CORS controls browser access to a response. It does not replace authentication, authorization, CSRF defenses, input validation, or rate controls.
- Testing with a different origin: A local tool, API client, or command-line request does not enforce browser CORS in the same way. Use
curlto inspect headers, then verify behavior in the browser.
When debugging related API issues, keep request data readable and reproducible. A JSON formatter can reveal whether the API returned an error object, while an API debugging tool can help compare headers across environments. These tools support diagnosis; the server’s CORS policy remains the actual fix.
When to revisit
Revisit this checklist whenever a frontend connects to a new API, a hostname or port changes, authentication moves from tokens to cookies, or a proxy, gateway, serverless function, or framework middleware is introduced. It is also worth repeating after a deployment that changes routing, TLS termination, error handling, or environment variables.
Before closing a CORS issue, run this short verification:
- Load the application from the real origin that users will visit.
- Test one simple request and one request that requires preflight.
- Test the intended credential mode, if any.
- Inspect successful and failed API responses for the expected CORS headers.
- Repeat the test through the deployed proxy or gateway, not only against a local server.
- Document the approved origins, methods, headers, and credential behavior for the next developer.
CORS configuration should be explicit, narrow enough for the application’s needs, and tested as part of the frontend and API workflow. When the browser reports a policy failure, treat the message as a starting point: identify the exact origin, inspect the preflight, compare headers, and verify every layer between the browser and the API.