CORS Errors in Production: A Debugging Checklist for APIs, Browsers, and Reverse Proxies

Overview

What you will get here is a practical checklist for cors errors troubleshooting in production environments, especially in enterprise web app stacks where browsers, identity flows, reverse proxies, and APIs all interact.

The most useful mental model is this: CORS is enforced by the browser, but the fix may live somewhere else. The browser decides whether frontend JavaScript can read a response from another origin. The response headers that allow or block that access may come from your application, your API gateway, your CDN, your ingress controller, or a reverse proxy sitting in front of everything.

Before changing anything, capture five facts:

1. Origin of the frontend: protocol, host, and port. For example, https://app.example.com.
2. Origin of the API: protocol, host, and port. For example, https://api.example.com.
3. HTTP method: GET, POST, PUT, PATCH, DELETE, and so on.
4. Whether credentials are involved: cookies, authorization headers, or client certificates.
5. Whether a preflight happened: an OPTIONS request before the actual request.

If you do not have those five facts, production CORS debugging becomes guesswork.

Also separate these three categories early:

• Not a CORS issue: DNS, TLS, routing, auth failure, or a plain 500 that the browser reports alongside a CORS message.
• Preflight issue: the OPTIONS request fails or returns incomplete headers.
• Actual response issue: the main request reaches the API, but the final response is not readable by the browser.

That distinction saves time because the same console message can hide very different failures.

Checklist by scenario

This section gives you a scenario-based path to fix CORS in production without jumping between browser tabs and infrastructure configs.

Scenario 1: The browser says the request was blocked by CORS, but Postman works

This is common and expected. Postman and server-to-server clients do not enforce browser CORS rules.

Checklist:

• Open the browser network tab and inspect the request pair. Look for an OPTIONS preflight before the main request.
• Confirm the frontend origin exactly. A mismatch between https://app.example.com and https://www.app.example.com matters.
• Check whether the response contains Access-Control-Allow-Origin.
• If credentials are used, verify Access-Control-Allow-Credentials: true is present.
• If credentials are used, verify Access-Control-Allow-Origin is not *.
• Check whether a proxy or CDN stripped or replaced the header.

Fix path: If Postman works but the browser fails, focus on response headers returned to the browser, not just backend business logic.

Scenario 2: The preflight request fails

A preflight request error usually means the browser sent OPTIONS first and did not receive the headers it needed to continue.

Checklist:

• Confirm the browser actually sent OPTIONS because of a non-simple method, custom header, or content type.
• Check the OPTIONS response status. A 200 or 204 is typical, but the key is that it completes successfully.
• Verify Access-Control-Allow-Methods includes the intended method.
• Verify Access-Control-Allow-Headers includes every custom request header the browser asked for, such as Authorization, Content-Type, or tracing headers.
• Confirm the route, gateway, or proxy is configured to handle OPTIONS and does not return 404, 405, or redirect.
• Make sure authentication middleware does not block OPTIONS before CORS headers are added.

Fix path: In many stacks, OPTIONS needs explicit handling at the edge layer. If your app code is correct but the gateway returns 405, the problem is upstream.

Scenario 3: GET works, but POST or PUT fails

This usually indicates a preflight difference rather than a complete CORS failure.

Checklist:

• Compare the working GET and failing POST in the network tab.
• Look for custom headers added only on write operations, such as Authorization, X-Requested-With, or tenant headers.
• Check whether the failing request sends Content-Type: application/json, which often triggers preflight.
• Verify the API or proxy allows the failing method in Access-Control-Allow-Methods.
• Check route-level policy differences. Some gateways treat write routes differently from read routes.

Fix path: Compare successful and failing requests field by field. Small header differences often explain why only certain methods fail.

Scenario 4: It only fails when cookies or sessions are involved

Credentialed requests make CORS stricter.

Checklist:

• Confirm the frontend request is actually sending credentials, such as fetch(..., { credentials: 'include' }) or the equivalent in your HTTP client.
• Verify the response includes Access-Control-Allow-Credentials: true.
• Verify Access-Control-Allow-Origin is a specific allowed origin, not a wildcard.
• Check cookie attributes such as SameSite and Secure. A missing cookie can look like a CORS problem when the real issue is cookie policy.
• Confirm redirects during login or token refresh are not crossing origins in unexpected ways.

Fix path: If your architecture relies on browser sessions, align your CORS setup with your cookie strategy. For a deeper comparison of auth patterns, see Bearer Token vs Session Cookie: Which Auth Pattern Fits Your Enterprise Web App?.

Scenario 5: The API returns the right CORS headers in app code, but the browser still fails

This is where cors reverse proxy issues usually appear.

Checklist:

• Inspect the final response received by the browser, not only what the backend emits locally.
• Check CDN, load balancer, API gateway, ingress controller, and reverse proxy behavior in order.
• Look for duplicate CORS headers added by more than one layer.
• Check whether one layer adds headers on 200 responses but not on 4xx or 5xx responses.
• Verify cached responses are not serving stale headers for the wrong origin.
• Check whether redirects cause the request to hit a different host with different CORS policy.

Fix path: CORS should usually be owned in one place, or at least governed clearly. Multiple layers writing overlapping headers make production behavior inconsistent.

Scenario 6: It fails only in production, not locally

Production introduces TLS termination, domain changes, stricter cookie behavior, and extra proxies.

Checklist:

• Compare exact origins between local and production, including ports and subdomains.
• Check for HTTP to HTTPS redirects that change origin behavior.
• Verify production ingress or gateway config matches local assumptions.
• Confirm environment variables for allowed origins are correct and include the real deployed frontend URL.
• Check if the production frontend uses a different auth flow, token refresh path, or asset domain.

Fix path: Local success often proves only that your application code can emit CORS headers. It does not prove the deployed request path preserves them.

Scenario 7: The error appears during token refresh or authenticated API calls

Teams often chase CORS when the deeper problem is identity or token validation.

Checklist:

• Check whether the refresh or API response is actually a 401 or 403.
• Confirm CORS headers are present even on auth failures, otherwise the browser hides useful details.
• Verify the Authorization header is allowed in preflight.
• Inspect issuer, audience, expiry, and signature issues separately from CORS.

Fix path: Keep auth troubleshooting separate. These guides may help: OAuth 2.0 Grant Types Comparison for Web Apps, SPAs, APIs, and Machine-to-Machine Services and JWT Token Errors Explained: Expired, Invalid Signature, Audience, and Issuer Troubleshooting.

What to double-check

Use this as your infrastructure-layer verification list whenever a CORS issue refuses to stay fixed.

Browser layer

• The origin is exact. Scheme, hostname, and port must match what the server expects.
• The browser console message is not treated as the sole source of truth. Always inspect the network trace.
• Preflight request headers such as Access-Control-Request-Method and Access-Control-Request-Headers match what your server permits.

Frontend client layer

• Your fetch or HTTP client includes credentials only when intended.
• You are not accidentally adding non-essential custom headers that trigger preflight.
• Environment-based API base URLs are correct for each deployment stage.

API application layer

• CORS middleware runs early enough in the request pipeline.
• Error responses and auth failures also receive CORS headers when appropriate.
• Allowed origins are explicit and maintained in configuration rather than scattered in code.

Gateway and reverse proxy layer

• OPTIONS is forwarded or handled correctly.
• Header rewriting rules do not remove or duplicate CORS headers.
• Per-route policies do not conflict with global defaults.

CDN and caching layer

• Responses with origin-dependent CORS headers are not cached incorrectly.
• If you dynamically echo allowed origins, ensure caching varies appropriately.
• Stale edge config is not masking a backend fix.

Security and auth layer

• Credentialed requests are using a compatible cookie and CORS policy.
• Authorization headers are included in allowed headers.
• Redirects to identity providers are expected and visible in the request chain.

A good operational rule is to test one failing browser request end to end and record the exact path: browser → CDN → gateway → proxy → app. If you cannot describe where headers are set, you probably do not yet control the issue.

Common mistakes

These are the patterns that repeatedly slow down production debugging.

• Assuming CORS belongs only to backend code. In corporate app workflows, ingress controllers, gateways, service meshes, and reverse proxies often own the effective behavior.
• Using wildcard origins with credentials. This is a common mismatch and will not work for cookie-based cross-origin browser access.
• Forgetting OPTIONS. Teams test the main endpoint and never confirm that the preflight path is routable and allowed.
• Allowing methods but not headers. Many requests fail because Authorization or Content-Type was not included in allowed headers.
• Inspecting only successful responses. CORS headers should also be considered on error responses, especially 401, 403, and 500 cases that frontend teams need to debug.
• Adding CORS in multiple places. This can produce inconsistent headers, duplicate values, or behavior that changes by route.
• Ignoring redirects. A login redirect, HTTP to HTTPS redirect, or API version redirect may move the request to a different origin or response path.
• Confusing missing cookies with CORS failure. Browser cookie rules and cross-site session behavior can create symptoms that look similar.

If your team handles APIs across multiple products, it is worth standardizing a CORS policy template the same way you standardize logging or health checks. That reduces one-off fixes and makes this part of your broader set of developer tools for cloud apps and deployment guardrails.

When to revisit

CORS policy should be revisited whenever your application boundaries change, not only when something breaks. This keeps the checklist useful over time and supports more predictable api debugging tools and workflows.

Revisit your CORS setup when:

• You add a new frontend domain, admin portal, partner portal, or staging environment.
• You move an API behind a new gateway, CDN, ingress controller, or reverse proxy.
• You change auth patterns, especially between bearer tokens and browser sessions.
• You introduce custom request headers for tenancy, tracing, feature flags, or compliance.
• You split a monolith into separate services with different origins.
• You enable edge caching or adjust cache policy around API responses.
• You update deployment workflows before a major release cycle or seasonal planning window.

A practical maintenance routine looks like this:

1. Create a small matrix of allowed origins, methods, headers, and credential behavior for each public-facing API.
2. Document which layer owns CORS: app, gateway, or proxy.
3. Add a browser-based test case for at least one credentialed and one non-credentialed request path.
4. Verify that 401, 403, and 500 responses still return the headers your frontend needs for diagnosis.
5. Review this matrix whenever infrastructure or auth workflows change.

If you treat CORS as production configuration rather than a one-time code snippet, incidents become shorter and onboarding becomes easier. That is the real value of an api CORS checklist: not just fixing today’s console error, but giving the team a stable method they can reuse whenever domains, proxies, or auth flows evolve.