How to Debug CORS Errors in Local Development and Production

Overview

If you need a quick way to debug CORS errors, start with this idea: the browser is enforcing a set of cross-origin rules based on the requesting origin, the HTTP method, the request headers, and the response headers. Most CORS failures are not backend crashes. They are policy mismatches.

CORS stands for Cross-Origin Resource Sharing. A browser treats requests as cross-origin when the scheme, host, or port differs between the page origin and the API origin. That means http://localhost:3000 calling http://localhost:8000 is already cross-origin because the ports differ. Likewise, https://app.example.com calling https://api.example.com is cross-origin because the subdomains differ.

When a CORS problem happens, the most useful shift is to stop thinking, “my fetch failed,” and start thinking, “what did the browser send, and what did the server return?” The browser console often shows a generic error message, but the Network tab usually contains the clues you actually need.

In practice, you are usually debugging one of five situations:

• The API response is missing Access-Control-Allow-Origin.
• A preflight OPTIONS request is failing.
• The server allows some methods or headers, but not the ones your app is sending.
• Credentials such as cookies are involved, and the response headers do not match that mode.
• A local proxy, CDN, gateway, serverless platform, or environment-specific config is changing behavior between development and production.

If you want a strong local setup before you begin, it helps to keep environments predictable. A checklist like Local Development Environment Checklist for New Web Projects is useful because many CORS issues start as basic mismatches in ports, env vars, or service URLs.

Core framework

Use this framework whenever you need a reliable CORS troubleshooting process. It works whether you are dealing with a React app in local development, an API behind a reverse proxy, or a production deployment on a cloud platform.

1. Confirm the exact origins involved

Write down both sides of the request:

• Frontend origin: where the page is running, such as http://localhost:5173 or https://app.example.com
• API origin: where the request is being sent, such as http://localhost:8080 or https://api.example.com

Do not assume two URLs are same-origin because they share a domain name. Port and protocol matter. Moving from HTTP to HTTPS also changes origin.

2. Check whether the request is simple or preflighted

Some browser requests are sent directly. Others trigger a preflight OPTIONS request first. Preflight usually appears when:

• You use methods other than simple ones like GET or POST
• You send custom headers such as Authorization or X-Requested-With
• You use a content type outside the simpler allowed set

If preflight happens, your server has to answer the OPTIONS request correctly before the real request is allowed. A common mistake is testing only the GET or POST handler and forgetting that the browser may never send it if the preflight fails first.

3. Inspect the Network tab, not just the console

Open browser dev tools and inspect the failing request. Look for:

• Status code for the main request or the preflight request
• The Origin request header
• The presence or absence of Access-Control-Allow-Origin
• Access-Control-Allow-Methods for preflight
• Access-Control-Allow-Headers for preflight
• Access-Control-Allow-Credentials if cookies or auth credentials are being used

Many teams lose time by reading only the frontend error message. The browser may say “blocked by CORS policy,” but the real issue could be a 404 on the preflight route, a 500 in middleware, or a redirect that strips needed headers.

4. Compare what the browser asked for with what the server allowed

This is the heart of most CORS troubleshooting. Ask four direct questions:

1. Did the browser send the expected Origin?
2. Did the response return a matching Access-Control-Allow-Origin?
3. If preflight occurred, did the server allow the requested method?
4. If preflight occurred, did the server allow the requested headers?

For example, if the browser sends Origin: http://localhost:3000 and the API responds with Access-Control-Allow-Origin: https://app.example.com, the browser will still block it during local development. The header has to match the actual requesting origin, or use a deliberate strategy that handles multiple allowed origins safely.

5. Treat credentials as a separate mode

If your frontend sends cookies or other credentials, your CORS config must be stricter and more explicit. In many setups, wildcard origin values are not valid with credentialed requests. If you see session or cookie-based auth working in same-origin pages but failing cross-origin, inspect:

• Whether the frontend request is explicitly sending credentials
• Whether the response includes Access-Control-Allow-Credentials
• Whether the allowed origin is specific rather than a wildcard

This is one reason local development and production often diverge. A token in local storage may work differently from a cookie-based session, even if the endpoint is the same.

6. Verify the response on the final layer that the browser sees

In production, your app may pass through multiple layers: app server, framework middleware, reverse proxy, CDN, edge function, API gateway, or serverless platform. You may think the backend is returning the right headers, but the browser only sees the final response after all intermediate layers have had their say.

This is especially important when deploying static frontends and separate APIs. If you use platforms discussed in How to Deploy a Static Website to Cloudflare Pages, Netlify, and Vercel, check how rewrites, redirects, headers, and serverless routes are configured in each environment.

7. Reproduce outside the frontend when useful

Browser CORS enforcement is a browser concern, but reproducing requests with API clients is still useful. A tool from a list like Best API Testing Tools for Frontend and Backend Developers can help you confirm whether the API itself is reachable and what raw headers it returns. Just remember: a successful API call in a non-browser client does not prove your browser CORS setup is correct.

Practical examples

Here are the patterns developers hit most often, along with the logic for fixing them.

Local frontend on one port, API on another

Suppose your frontend runs on http://localhost:3000 and your API runs on http://localhost:8000. The browser sends Origin: http://localhost:3000. Your API needs to respond with an appropriate Access-Control-Allow-Origin value for that origin. If you are sending JSON with auth headers, your API may also need to answer preflight with allowed methods and headers.

If you are tired of dealing with CORS in local development, a development proxy can help. Instead of calling the API directly from the browser, the frontend dev server proxies requests so they appear same-origin from the browser’s perspective. This can simplify local work, but it can also hide real production behavior. Use a proxy as a workflow tool, not as a substitute for understanding your actual deployment model.

Preflight fails before the real request is sent

You make a POST request with an Authorization header, but the browser shows a CORS error and your controller logs show no POST request arriving. Usually that means the preflight OPTIONS request failed.

Check whether your server or framework:

• Has an OPTIONS route or middleware path for the endpoint
• Returns the allowed method, such as POST
• Returns the allowed headers, such as Authorization and Content-Type
• Stops redirects or auth checks from interfering with the preflight

A common production bug is middleware that protects all routes, including OPTIONS. If the preflight is redirected to login or rejected before CORS headers are applied, the browser blocks the request.

Works in Postman, fails in the browser

This is one of the most common CORS troubleshooting moments. The explanation is simple: browser security policy is stricter than a general API client. If the API works in a client but fails in the browser, your endpoint may be fine while your browser-facing CORS policy is incomplete.

That distinction matters during debugging. Use browser dev tools to inspect policy behavior, and use API tools to inspect response content and status. They answer different questions.

Production subdomain split: app.example.com to api.example.com

This architecture is common and reasonable, but it requires explicit CORS handling. If your frontend origin is https://app.example.com and your API is https://api.example.com, configure the API to allow the frontend origin. If the app uses cookies for authentication, make sure your credential mode and cookie settings are compatible with cross-origin usage.

If deployments differ across environments, store allowed origins in environment variables or config files so local, staging, and production remain easy to reason about. A guide like How to Set Up Environment Variables for Local, Staging, and Production is helpful here, because hardcoded origins are a classic source of surprises during release.

CORS error that is really a redirect or 404 problem

Sometimes the browser reports a CORS issue because the request path is wrong, a rewrite rule is broken, or the route redirects somewhere unexpected. For example:

• The frontend calls /api/users in production, but the real deployed path is /v1/users
• The CDN redirects HTTP to HTTPS but omits expected CORS headers on the redirect response
• The API returns a framework-generated 404 page without CORS headers

In all of these cases, developers may stare at CORS config while the true issue is routing. Always inspect the exact status code, response location, and final URL.

Common mistakes

This section gives you a compact list of CORS mistakes worth checking before you change architecture or rewrite middleware.

Assuming CORS belongs only to the frontend

CORS is enforced by the browser, but the fix is usually in the server response. Frontend code can trigger the issue, but cannot grant itself permission.

Using overly broad settings without understanding credentials

Developers sometimes try a wildcard origin everywhere and expect cookie-based auth to keep working. Credentialed cross-origin requests usually need more specific treatment than that.

Forgetting that localhost ports count as different origins

This catches people early and often. localhost:3000 and localhost:8000 are cross-origin. So are 127.0.0.1 and localhost.

Debugging only the main request and ignoring preflight

If the browser sends an OPTIONS request first, that request must succeed. Your API logs may look confusing until you realize the browser never sent the real request.

Checking application code but not platform config

Headers can be added, removed, or bypassed by reverse proxies, gateways, and hosting rules. If you recently changed hosting, DNS, or domain setup, review your edge config and routing assumptions. Articles like How to Connect a Domain to Your Web App: DNS Records Explained Simply and Best Web App Hosting Platforms for Small Projects and Side Hustles are useful context when CORS issues appear after moving environments.

Hardcoding one environment’s origin into another

An API that allows only http://localhost:3000 will fail when deployed behind https://app.example.com. Likewise, production-only values break local testing. Keep origin lists explicit and environment-aware.

Misreading a network failure as a CORS failure

If the API host is down, DNS is wrong, TLS is broken, or a firewall is blocking the request, the browser may still surface a message that looks like CORS. Verify that the target URL is reachable and correct before assuming your headers are the only problem.

When to revisit

CORS is not something you set once and forget. Revisit your configuration whenever the shape of your app changes, especially if requests cross new origins or pass through new infrastructure.

Review your CORS setup when:

• You add a new frontend origin, such as staging, preview, admin, or docs
• You move from local token auth to cookie-based sessions
• You introduce a CDN, API gateway, reverse proxy, or edge platform
• You add custom headers or change content types
• You split a monolith into separate frontend and API deployments
• You change domain names, subdomains, ports, or HTTPS behavior
• You adopt a dev proxy that differs from production routing

A practical habit is to keep a short CORS checklist in your project docs:

1. List allowed origins per environment.
2. List which endpoints must answer preflight.
3. List whether credentials are used.
4. Document where headers are set: app code, middleware, proxy, or platform config.
5. Test one browser-based request in local, staging, and production after major changes.

If your project uses Node-based tooling, it also helps to keep runtime changes under control. Even unrelated environment drift can make debugging harder than it needs to be. For teams that switch versions often, Node Version Managers Compared: nvm, fnm, Volta, and asdf is a useful companion read.

The simplest way to think about CORS troubleshooting is this: identify the origin, inspect the request, inspect the response, and verify the final deployment layer. Once you adopt that sequence, CORS stops feeling like a browser mystery and starts behaving like a normal HTTP debugging task. Save this guide for the next time a local port changes, a staging domain is added, or a production proxy gets introduced. Those are the moments when CORS bugs tend to come back.