A CORS error means a browser refused to expose a cross-origin response to your frontend. This guide gives you a repeatable way to inspect the failing request, understand preflight behavior, correct response headers, and handle credentials without weakening your API’s security.
Overview
Cross-Origin Resource Sharing (CORS) controls how browser-based JavaScript can communicate with a different origin. An origin is defined by its scheme, host, and port. For example, https://app.example.com and https://api.example.com have different origins even though they share a parent domain. Likewise, http://localhost:3000 and http://localhost:8000 are different origins during local development.
CORS is enforced by browsers, not usually by the API client itself. A request can reach the server and still appear to fail in frontend code because the browser blocks JavaScript from reading the response. A request made directly from a backend service, command-line client, or server-side job does not use the browser’s CORS enforcement model.
The fastest troubleshooting approach is to separate three questions:
- Did the browser send the request, including any preflight request?
- Did the server return the required CORS headers on the relevant response?
- Do the requested origin, method, headers, and credentials match the server’s configuration?
Do not begin by adding a broad wildcard origin everywhere. First identify the exact origin and request shape. A narrow, testable configuration is easier to secure and maintain.
Checklist by scenario
Scenario 1: A simple cross-origin request fails
- Open browser DevTools and select the Network panel.
- Reload the page and locate the failed API request.
- Record the request URL, request origin, status code, method, and response headers.
- Check whether the response includes
Access-Control-Allow-Originwith the exact frontend origin, such ashttps://app.example.com. - Confirm that the server adds the header on error responses as well as successful responses.
For a request from https://app.example.com, a compatible response might include:
Access-Control-Allow-Origin: https://app.example.com
The scheme, hostname, and port must match. A trailing slash is not part of an origin, but differences such as http versus https, or one port versus another, matter.
Scenario 2: The browser sends a CORS preflight request
A browser may send an OPTIONS request before the actual request when the method, headers, or content type requires permission to be checked. This is called a CORS preflight request. In DevTools, look for an OPTIONS request immediately before the failed request.
The preflight commonly includes headers such as:
Origin: https://app.example.com
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: authorization, content-type
The server must answer the preflight with compatible permissions, for example:
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Check each item rather than treating the preflight as a generic failure. The allowed method must include the method the browser requested. Every non-simple request header that the browser asks to send must be permitted. The server, reverse proxy, or platform hosting the API must also return a successful response to OPTIONS without requiring application authentication that the preflight cannot provide.
Scenario 3: The request includes cookies or another credential
When a frontend sends cookies or uses a credentialed request, the client and server must agree explicitly. A frontend request may look like this:
fetch('https://api.example.com/profile', {
credentials: 'include'
});
The server response should identify the permitted origin and include:
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
Do not combine Access-Control-Allow-Credentials: true with Access-Control-Allow-Origin: *. If credentials are required, configure an explicit allowlist of trusted origins. Also check cookie attributes, including domain, path, secure transport, and same-site behavior. A CORS header cannot make a cookie eligible to be sent if the cookie itself is not acceptable to the browser.
Scenario 4: An authorization header causes the failure
Adding an Authorization header commonly changes a request’s CORS requirements because that header must be declared in the preflight response. Confirm that the API returns Authorization in Access-Control-Allow-Headers and that the authentication middleware does not reject OPTIONS requests before CORS handling runs.
If you are inspecting a token while debugging, use a test token and avoid pasting live secrets into browser-based utilities. The JWT Decoder Guide explains how to inspect claims safely without treating decoded content as proof that a token is valid.
Scenario 5: Local, staging, and production behave differently
Compare the complete origins in each environment. A local frontend might use http://localhost:3000, while staging uses https://staging.app.example.com. These are separate allowlist entries. Check environment variables, deployment secrets, reverse-proxy configuration, and whether a platform routes API and OPTIONS requests to the same service.
A typical backend configuration should conceptually contain an allowlist rather than a single hard-coded development origin:
allowedOrigins = [
"http://localhost:3000",
"https://staging.app.example.com",
"https://app.example.com"
]
The implementation differs by framework, but the decision should be made from the incoming origin and the response should return that origin only when it is approved. When responses vary by origin, configure the relevant caching behavior, commonly with Vary: Origin, so a cache does not reuse one origin’s response for another.
What to double-check
| Item | What to verify | Typical symptom |
|---|---|---|
Access-Control-Allow-Origin | Matches the requesting frontend origin or uses a deliberate public policy. | Browser reports that the origin is not allowed. |
Access-Control-Allow-Methods | Includes the method requested by the browser. | Preflight fails for PUT, PATCH, or DELETE. |
Access-Control-Allow-Headers | Includes requested headers such as Authorization and Content-Type. | Preflight fails after adding a custom header. |
Access-Control-Allow-Credentials | Is true when cookies or other credentials are intentionally used. | Credentialed response is blocked. |
OPTIONS routing | Reaches CORS handling and returns without an inappropriate authentication failure. | Preflight returns 401, 403, 404, or a redirect. |
| Redirects | The API and preflight path do not unexpectedly redirect between schemes or URLs. | Browser reports a failed CORS request despite correct-looking headers. |
| Response errors | CORS headers are present on 4xx and 5xx responses where appropriate. | Successful calls work, but errors appear as opaque CORS failures. |
Use the Network panel’s request and response headers as the source of truth. A framework configuration file may look correct while a load balancer, API gateway, serverless adapter, or web server changes the final response.
Common mistakes
- Fixing the frontend only: CORS permission is primarily communicated by the server response. Changing fetch syntax cannot authorize an origin that the server has not allowed.
- Using a wildcard during credentialed requests: Explicit origins are required for a credentialed policy. Keep the allowlist limited to origins that should access the API.
- Allowing methods but not headers: A server can permit
POSTwhile still rejecting a preflight that requestsAuthorizationor a custom header. - Handling only successful responses: Middleware order can cause CORS headers to disappear on exceptions, validation failures, or authentication errors.
- Testing with an extension and assuming production works: Browser extensions or disabled web security can hide a real deployment problem. Reproduce the request in a normal browser profile.
- Confusing CORS with authentication: A valid token does not grant cross-origin permission, and a valid CORS response does not authenticate a user.
- Changing several layers at once: Modify one boundary at a time—application, proxy, gateway, or hosting platform—then inspect the resulting response.
For a broader, repeatable frontend diagnosis process, use the Frontend Developer Workflow Checklist. Accessibility and browser testing should remain separate checks; CORS success does not confirm that an interface works for all users. See the Web Accessibility Testing Tools workflow for that part of release validation.
When to revisit
Recheck CORS whenever an input to the browser-to-API connection changes. Useful checkpoints include:
- Adding a new frontend domain, preview deployment, staging environment, or local development port.
- Moving an API behind a new proxy, gateway, CDN, serverless platform, or load balancer.
- Introducing cookies, refresh tokens, an
Authorizationheader, or another custom request header. - Changing methods, content types, redirects, authentication middleware, or error handling.
- Upgrading a framework or CORS library and reviewing its configuration defaults.
- Verifying a release after a seasonal planning cycle, infrastructure change, or workflow update.
Before acting on a new CORS error, run this short checklist:
- Copy the exact frontend origin from the failed request.
- Inspect whether an
OPTIONSpreflight exists. - Compare requested methods and headers with the server’s allow headers.
- Confirm whether credentials are being sent and whether the policy supports them.
- Inspect the final response after every proxy or redirect.
- Test an approved origin, an unapproved origin, and the relevant error response.
- Document the allowed origins and the deployment layer responsible for each rule.
Keep this checklist with your API deployment notes. CORS problems are easiest to resolve when the browser request, server policy, and infrastructure path are examined together rather than treated as a mysterious frontend error.