CORS Errors Explained: A Practical Debugging Workflow for Web APIs

Overview

Cross-Origin Resource Sharing, or CORS, is a browser security mechanism. A web page served from one origin may request a resource from another origin, but the browser checks whether the server explicitly permits that interaction. 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.

The browser sends an Origin request header and expects the API response to contain a compatible Access-Control-Allow-Origin value. For some requests, the browser first sends an OPTIONS preflight request to ask whether the actual request is permitted. If the preflight or actual response fails the browser's checks, JavaScript usually receives a generic CORS error instead of the response body.

CORS is enforced by browsers, not by the HTTP protocol itself. A request made from a backend service, command-line client, or API testing tool can succeed while the same request fails in a browser. That difference is useful evidence: it often means the API is reachable, but its browser-facing policy is incomplete or mismatched.

Start with the browser's Network panel rather than changing random frontend code. Identify whether the failing entry is an OPTIONS preflight or the actual method such as GET, POST, PUT, or DELETE. Then compare the request headers and response headers against the expected origin and permissions.

Checklist by scenario

Scenario 1: A basic GET request is blocked

1. Copy the exact page origin from the browser address bar, including scheme and port.
2. Check that the API response includes Access-Control-Allow-Origin.
3. Confirm its value matches the requesting origin, or is an appropriate wildcard for a request without credentials.
4. Check that the API route returns the header on error responses as well as successful responses.
5. Verify that a proxy, CDN, or load balancer is not removing or replacing the header.

A common mismatch is allowing http://localhost:3000 while the frontend is actually running at http://localhost:5173. Different ports create different origins. The same applies to http versus https, and to a hostname versus an IP address.

Scenario 2: The browser sends an OPTIONS preflight

A preflight commonly appears when the request uses a non-simple method, sends headers such as Authorization or Content-Type: application/json, or otherwise needs permission before the browser sends the actual request. Inspect the OPTIONS response first.

• Access-Control-Allow-Origin should permit the requesting origin.
• Access-Control-Allow-Methods should include the intended method.
• Access-Control-Allow-Headers should include requested non-safelisted headers, such as Authorization or Content-Type.
• The response should have a successful status that your server and infrastructure handle consistently.
• The preflight should not be redirected to a login page, trailing-slash route, or different host.

The browser sends useful preflight details in Access-Control-Request-Method and Access-Control-Request-Headers. Treat these as a direct statement of what permission the browser is asking for. If the request asks for authorization but the response only allows content-type, the preflight is incomplete.

Scenario 3: Authentication or cookies are involved

For cookie-based sessions, the frontend may use credentials: "include". The server must then return Access-Control-Allow-Credentials: true and a specific allowed origin rather than a wildcard. The cookie itself also has independent attributes, such as its domain, path, and cross-site policy, so a successful CORS response does not guarantee that the browser will send or accept the cookie.

For bearer tokens, check whether the frontend sends an Authorization header. That header commonly triggers preflight and must be allowed by the API. A CORS error can hide a 401 or 403 response, so inspect the Network panel and server logs before concluding that the token is invalid. For a safe way to inspect token claims, see the JWT debugging guide; do not paste live credentials into an untrusted tool.

Scenario 4: The request works in curl but not in the browser

This is expected when the command-line request does not reproduce browser behavior. Add an Origin header and, when relevant, simulate the preflight:

curl -i https://api.example.test/users \
  -H "Origin: https://app.example.test"

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"

Compare the output with the browser's request. This test can reveal whether the backend emits the expected headers, but it does not replace testing in the browser because the browser applies the final enforcement.

Scenario 5: The error appears after deployment

Compare local and deployed values rather than assuming the application code changed. Check the frontend's API base URL, the deployed origin, environment variables, TLS scheme, reverse-proxy configuration, and whether the production API uses a different authentication mechanism. A deployment can also expose a missing route for OPTIONS or a proxy that handles OPTIONS before the application does.

What to double-check

Use this header reference while reading the Network panel:

Also check the response status, redirect chain, and response body. A route returning a framework-generated 404, a proxy-generated 502, or a login redirect may not include the CORS headers even if the success path does. This is why testing only a successful API call can miss the real production failure.

Keep the allowed-origin list narrow and intentional. Do not treat CORS as an access-control replacement: it does not authenticate users or prevent non-browser clients from calling an API. Authentication, authorization, CSRF protections where applicable, input validation, and rate controls remain separate backend responsibilities.

Minimal backend configuration pattern

The exact syntax depends on the server framework, but the logic is consistent: define trusted origins, handle preflight, allow only required methods and headers, and apply the policy to error responses too. In an Express-style application, configuration may look conceptually like this:

const allowedOrigins = new Set([
  "https://app.example.test",
  "http://localhost:5173"
]);

app.use(cors({
  origin: (origin, callback) => {
    if (!origin || allowedOrigins.has(origin)) {
      callback(null, true);
    } else {
      callback(new Error("Origin not allowed"));
    }
  },
  methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
  allowedHeaders: ["Content-Type", "Authorization"],
  credentials: true
}));

Use the equivalent middleware or server configuration for your stack, and verify the generated response rather than relying only on configuration intent. If you are troubleshooting a malformed API payload alongside CORS, a JSON formatter and validator can help separate response syntax problems from browser policy problems.

Common mistakes

• Adding mode: "no-cors" as a fix. This produces an opaque response that frontend JavaScript cannot read. It does not grant normal API access.
• Allowing every origin during a production fix. A broad policy may hide configuration errors and expose more browser-based access than intended. Start with the exact frontend origins required.
• Returning a wildcard with credentials. Credentialed requests require a specific origin response, not *.
• Allowing methods but not headers. A POST can still fail preflight if Authorization or Content-Type is missing from the allowed-header policy.
• Debugging only the frontend. CORS response headers come from the API or an intermediary. Check application logs, proxy rules, and deployment configuration.
• Confusing CORS with an authentication failure. Inspect status codes, cookies, token claims, and server logs. A token can be expired even when the CORS policy is correct.
• Ignoring caching. If allowed origins vary, review cache behavior and the Vary: Origin response. A cached response for one origin may not be appropriate for another.

When to revisit

Return to this checklist whenever a frontend connects to a new API, a development port changes, a domain moves from HTTP to HTTPS, authentication changes from cookies to tokens or back, or a reverse proxy and deployment platform is introduced. Recheck it after changing framework middleware, API routes, allowed headers, or environment-variable handling.

For a practical incident workflow, save the failing request as evidence: record the page origin, API URL, method, status, request headers, preflight result, redirect chain, and server-side log entry. Then run the following sequence:

1. Reproduce the issue with browser DevTools open to the Network panel.
2. Classify the failure as preflight, actual response, redirect, network, or authentication.
3. Compare the exact origin and requested headers with the API's CORS policy.
4. Test the preflight and actual request independently where possible.
5. Make the smallest backend or infrastructure change that addresses the mismatch.
6. Retest success, authentication failure, validation failure, and not-found responses.

Keep a small integration test or documented curl command for each supported frontend origin. That turns CORS debugging from trial and error into a repeatable check whenever workflows or tools change.