CORS Errors Explained: Debug Preflight Requests, Headers, and Credentials

Overview

Cross-Origin Resource Sharing (CORS) is the browser’s way of enforcing a server-approved boundary between origins. An origin is the combination of 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. A local frontend at http://localhost:5173 is also a different origin from an API at http://localhost:8000.

A browser may send the request to the server, but refuse to expose the response to JavaScript unless the response contains an appropriate Access-Control-Allow-Origin header. This is why a request can appear successful in server logs while the frontend reports a CORS error.

Browser-to-server request flow

Frontend JavaScript
      |
      | 1. Simple request, or OPTIONS preflight
      v
Browser --------------------> API server
      |                         |
      |                         | Checks Origin, method,
      |                         | headers, and credentials
      |                         |
      | 2. Response with CORS headers
      <-------------------------
      |
      | 3. Browser exposes or blocks
      |    the response for JavaScript

A request is more likely to trigger a preflight when it uses a method such as PUT, PATCH, or DELETE, sends non-simple request headers, or uses a content type outside the browser’s simple-request rules. The preflight is an OPTIONS request containing headers such as Origin, Access-Control-Request-Method, and Access-Control-Request-Headers.

CORS is not an authentication system. It does not protect an API from command-line clients, server-side programs, or malicious requests that omit browser enforcement. Use authentication, authorization, CSRF protections where applicable, rate limits, and input validation separately.

Checklist by scenario

Scenario 1: A basic GET request is blocked

1. Open the browser’s Network panel and inspect the failed request.
2. Record the exact request Origin, including scheme, hostname, and port.
3. Check whether the API response includes Access-Control-Allow-Origin.
4. Confirm that its value exactly matches the allowed frontend origin, or is an intentionally broad policy for a non-credentialed public endpoint.
5. Check redirects. A redirect from the API to a login page, another hostname, or an HTTP endpoint can create a separate CORS failure.

Scenario 2: An OPTIONS preflight fails

1. Find the OPTIONS request immediately before the failed request.
2. Confirm the server, reverse proxy, or platform routes OPTIONS to a response rather than rejecting it at authentication or method filtering.
3. Return the requested method in Access-Control-Allow-Methods.
4. Return every requested non-simple header in Access-Control-Allow-Headers, such as Authorization or Content-Type.
5. Return a successful status and a complete CORS response. A server may use 204 No Content or another successful response appropriate to its framework.

Scenario 3: Cookies or other credentials are involved

1. Set credentials: 'include' in the browser request when cross-origin cookies are intended.
2. Return a specific origin in Access-Control-Allow-Origin; do not combine * with Access-Control-Allow-Credentials: true.
3. Return Access-Control-Allow-Credentials: true on the relevant response and, where needed, the preflight response.
4. Check cookie attributes separately. Cross-site cookie behavior can depend on SameSite, Secure, domain, path, and browser policy.
5. Verify that the API’s session or authentication middleware does not reject OPTIONS before CORS handling runs.

Scenario 4: It works locally but fails after deployment

1. Compare the deployed frontend origin with the local origin. A production hostname, preview URL, and custom domain are separate origins.
2. Check the production reverse proxy, CDN, serverless function, and API gateway independently.
3. Inspect redirects caused by HTTP-to-HTTPS rules, trailing-slash rules, or authentication middleware.
4. Confirm that environment variables contain the deployed API URL and an allowed origin, rather than a local development value.
5. Test from the actual browser origin instead of relying only on an API client that does not enforce CORS.

Quick decision tree

Is the error reported by browser JavaScript? If no, investigate the network, server, or application error first. If yes, continue. Is there an OPTIONS request? If yes, fix its status and CORS response headers before investigating the actual request. If no, inspect the actual response for Access-Control-Allow-Origin. Are cookies or credentials used? If yes, use an explicit origin and credential-compatible cookie settings. If no, check the origin, method, and requested headers. Does the response pass through a proxy or CDN? If yes, verify that it preserves CORS headers and varies cached responses by Origin when the allowed origin is dynamic.

Header reference

Copy-paste configurations

These are starting patterns, not universal drop-in policies. Replace the example origin with the frontend origin you actually intend to allow, and keep the allowlist as narrow as the application permits.

Express

import cors from 'cors';

app.use(cors({
  origin: ['https://app.example.com'],
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
  maxAge: 600
}));

Register CORS before routes that need it. If the origin is selected dynamically, validate it against an allowlist and ensure the response varies by Origin.

Nginx

location /api/ {
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin 'https://app.example.com' always;
        add_header Access-Control-Allow-Methods 'GET, POST, PUT, PATCH, DELETE, OPTIONS' always;
        add_header Access-Control-Allow-Headers 'Content-Type, Authorization' always;
        add_header Access-Control-Allow-Credentials 'true' always;
        add_header Access-Control-Max-Age 600 always;
        return 204;
    }

    add_header Access-Control-Allow-Origin 'https://app.example.com' always;
    add_header Access-Control-Allow-Credentials 'true' always;
    proxy_pass http://api_upstream;
}

Use care with Nginx conditionals and inherited add_header directives. Confirm both preflight and ordinary responses in the Network panel.

Apache

<IfModule mod_headers.c>
    Header always set Access-Control-Allow-Origin "https://app.example.com"
    Header always set Access-Control-Allow-Methods "GET, POST, PUT, PATCH, DELETE, OPTIONS"
    Header always set Access-Control-Allow-Headers "Content-Type, Authorization"
    Header always set Access-Control-Allow-Credentials "true"
</IfModule>

Make sure Apache or the upstream application responds to OPTIONS, and ensure the required headers are not removed by another virtual host or proxy rule.

Django

# settings.py
INSTALLED_APPS = [
    # ...
    'corsheaders',
]

MIDDLEWARE = [
    'corsheaders.middleware.CorsMiddleware',
    # ...
]

CORS_ALLOWED_ORIGINS = [
    'https://app.example.com',
]
CORS_ALLOW_CREDENTIALS = True
CORS_ALLOW_HEADERS = [
    'accept', 'content-type', 'authorization',
]

Place the CORS middleware early enough to add headers to responses produced by other middleware. Keep CSRF configuration separate; allowing a CORS origin does not automatically authorize state-changing browser requests.

Laravel

// config/cors.php
return [
    'paths' => ['api/*', 'sanctum/csrf-cookie'],
    'allowed_methods' => ['*'],
    'allowed_origins' => ['https://app.example.com'],
    'allowed_origins_patterns' => [],
    'allowed_headers' => ['Content-Type', 'Authorization'],
    'exposed_headers' => [],
    'max_age' => 600,
    'supports_credentials' => true,
];

After changing configuration, clear the framework’s cached configuration when appropriate for your deployment. If using cookie-based authentication, configure the session domain, secure transport, and CSRF flow as a separate checklist.

Serverless functions

export default async function handler(request) {
  const origin = 'https://app.example.com';
  const headers = {
    'Access-Control-Allow-Origin': origin,
    'Access-Control-Allow-Credentials': 'true',
    'Access-Control-Allow-Methods': 'GET,POST,PUT,PATCH,DELETE,OPTIONS',
    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    'Access-Control-Max-Age': '600'
  };

  if (request.method === 'OPTIONS') {
    return new Response(null, { status: 204, headers });
  }

  return new Response(JSON.stringify({ ok: true }), {
    status: 200,
    headers: { ...headers, 'Content-Type': 'application/json' }
  });
}

For a deployed function, apply the same pattern in the platform’s runtime or middleware. If a CDN, gateway, or edge proxy sits in front of the function, check that it forwards OPTIONS and preserves the response headers.

What to double-check

• Origin spelling: https://app.example.com, http://app.example.com, and https://app.example.com:8443 are different origins.
• Response coverage: Add CORS headers to successful responses and relevant error responses, not only the happy path.
• Credentials: A wildcard origin is incompatible with credentialed browser requests. Use an explicit allowlist.
• Headers versus exposed headers: Access-Control-Allow-Headers controls what the browser may send. Access-Control-Expose-Headers controls which response headers frontend JavaScript may read.
• Cache behavior: If the server reflects approved origins, include Vary: Origin and inspect CDN caching rules.
• Preflight caching: A browser may reuse a successful preflight. Clear site data, wait for the cache to expire, or temporarily reduce Access-Control-Max-Age while testing.
• Authentication redirects: An unauthenticated OPTIONS request should not be redirected to a login page.
• Tool limitations: curl, API clients, and server-to-server tests can confirm server responses but do not reproduce all browser CORS enforcement.

Common mistakes

The most common mistake is adding Access-Control-Allow-Origin: * everywhere without checking whether the application uses cookies or authorization-sensitive browser requests. Another is allowing the origin but forgetting that a preflight also needs the requested method and headers. Adding CORS only in the frontend cannot fix the problem: the API or the layer serving the API must provide the response headers.

It is also easy to test the wrong URL. A frontend may call a development API while the deployed build uses an environment variable, a proxy path, or a different subdomain. Inspect the final request URL rather than assuming the source configuration is active.

Finally, avoid treating CORS as a substitute for access control. A permissive CORS policy may be appropriate for a genuinely public read-only endpoint, but it does not make private data safe. Authentication and authorization must still be enforced on the server.

When to revisit

Keep this checklist with the deployment workflow and revisit it whenever a frontend changes domain, a new preview environment is added, an API moves behind a proxy or CDN, authentication changes, or a new method or request header is introduced. It is especially useful to repeat the check after switching frameworks, serverless runtimes, hosting providers, or deployment pipelines, because the layer handling OPTIONS may have changed.

For a practical final pass, test one simple request, one preflighted request, and one credentialed request if your application uses cookies. Test them from the production origin and from each supported preview origin. Save the browser Network-panel details, the server response headers, and the configured allowlist with the project’s deployment notes. That record makes the next browser API request blocked error faster to diagnose and reduces the chance of fixing only the local environment.