CORS Errors Explained: Debug Preflight Requests, Credentials, Headers, and CDN Configuration
CORSAPIsHTTPBrowser debuggingWeb security

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

TTeckSite Editorial Team
2026-11-15
7 min read

Use this practical CORS checklist to diagnose preflight failures, credentials, headers, redirects, proxies, CDNs, and environment mismatches.

CORS errors usually mean the browser sent a request that the server did not explicitly permit. This guide gives you a repeatable checklist for separating preflight failures, missing response headers, credentials issues, redirects, private-network requests, and CDN or reverse-proxy configuration problems.

Overview

Cross-Origin Resource Sharing, or CORS, is a browser security mechanism. A page loaded from one origin may request a resource from another origin, but the browser checks whether the destination has granted permission. An origin is the combination of scheme, host, and port, so https://app.example.com, http://app.example.com, and https://api.example.com are different origins.

The server grants access with response headers such as Access-Control-Allow-Origin. For some requests, the browser first sends an OPTIONS preflight request describing the intended method and headers. The server must answer that preflight correctly before the browser sends the actual request.

A useful mental model is:

  1. The browser sends a request, or sends an OPTIONS preflight first.
  2. The server, application, CDN, or reverse proxy returns a response.
  3. The browser checks the CORS headers before exposing the response to JavaScript.

CORS is enforced by browsers. A successful request made with curl or a backend HTTP client does not prove that browser JavaScript will be allowed to read the response. For a broader request-inspection workflow, see the Chrome DevTools Network Tab Guide.

Checklist by scenario

Scenario 1: The request has no preflight

Start by opening DevTools, selecting the request in the Network panel, and checking the Request URL, request method, request headers, status, and response headers. If the request is a simple cross-origin request, the browser may send it directly. The response still needs an appropriate Access-Control-Allow-Origin value before JavaScript can read it.

The value must match the requesting origin, including scheme and port. For example:

Access-Control-Allow-Origin: https://app.example.com

For a public, non-credentialed endpoint, a wildcard may be appropriate:

Access-Control-Allow-Origin: *

Do not treat the wildcard as a general solution. It cannot be combined with credentialed browser requests.

Scenario 2: The browser sends an OPTIONS preflight

A preflight commonly occurs when the request uses a method such as PUT, PATCH, or DELETE, or includes non-safelisted request headers such as a custom header or an authorization header. In DevTools, inspect the OPTIONS request separately from the later application request.

A typical preflight contains headers like these:

OPTIONS /v1/profile HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: PATCH
Access-Control-Request-Headers: authorization, content-type

The response needs to allow the origin, method, and requested headers:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, PATCH, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Vary: Origin

The exact status is less important than returning a successful response that reaches the browser with the required headers. Confirm that authentication middleware, routing rules, and access controls do not reject OPTIONS before CORS handling runs.

Scenario 3: Credentials are involved

Credentials include cookies and other browser-managed authentication information. If the frontend deliberately sends credentials, it must opt in, for example with fetch:

fetch('https://api.example.com/account', {
  credentials: 'include'
});

The server must then return an explicit origin and:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Credentials: true
Vary: Origin

This combination is invalid for credentialed access:

Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

Also check cookie attributes and domain rules separately. A correct CORS response does not guarantee that a cookie will be sent or accepted.

Scenario 4: The browser reports a wildcard or origin mismatch

Compare the browser's Origin request header with the server's Access-Control-Allow-Origin response header. Watch for a changed port, an http versus https mismatch, a trailing slash, or a staging hostname being absent from the allowlist. The header contains an origin, not a full URL with a path.

If the server dynamically reflects approved origins, keep the allowlist explicit and add Vary: Origin so a cache does not reuse one origin's response for another.

Scenario 5: Redirects appear in the request chain

Inspect every response in the Network panel, including redirects from HTTP to HTTPS, a bare hostname to a canonical hostname, or an API route to an authentication page. The final response and any relevant redirect response must be compatible with the browser's CORS processing. Avoid relying on a redirect as part of a preflight path; expose the final API endpoint directly where possible.

Scenario 6: A private-network request is blocked

When a public page attempts to reach a service on a more-private network, the browser may perform an additional permission check. If DevTools shows a private-network access failure, inspect the preflight request and the browser's requested headers. The server may need to return an explicitly enabled private-network response header, subject to the browser and deployment environment in use. Treat this as a separate compatibility check rather than adding broad CORS permissions to every endpoint.

Scenario 7: The application works locally but fails behind a proxy or CDN

Test the deployed hostname, not only the application process. A reverse proxy or CDN may answer OPTIONS itself, remove headers, cache an outdated response, or route the preflight to a different origin. Confirm that CORS headers are present on successful responses and relevant error responses, and that the proxy forwards the Origin, Access-Control-Request-Method, and Access-Control-Request-Headers request headers.

A framework-level configuration might look like this in Express:

import cors from 'cors';

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

For an Nginx-style deployment, apply equivalent headers at the layer that actually handles the request, and ensure OPTIONS is not blocked before those headers are added:

add_header Access-Control-Allow-Origin "https://app.example.com" always;
add_header Access-Control-Allow-Methods "GET, POST, PATCH, OPTIONS" always;
add_header Access-Control-Allow-Headers "Content-Type, Authorization" always;

if ($request_method = OPTIONS) {
    return 204;
}

Adapt examples to your framework and proxy. Do not copy a permissive development configuration into production without reviewing its origin and credential behavior.

Browser versus curl

TestWhat it tells youWhat it does not prove
Browser fetchWhether browser CORS policy allows JavaScript to read the responseWhether a backend client can call the API
curl with OriginWhich CORS headers the server returns for a chosen originHow the browser will handle every redirect or credential rule
curl OPTIONSWhether the preflight route responds to the requested method and headersWhether the frontend uses the same URL, headers, and credentials

Example preflight test:

curl -i -X OPTIONS 'https://api.example.com/v1/profile' \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: PATCH' \
  -H 'Access-Control-Request-Headers: authorization, content-type'

What to double-check

  • Origin: Is the exact frontend scheme, host, and port allowed?
  • Methods: Does Access-Control-Allow-Methods include the actual method?
  • Headers: Does it include every requested non-safelisted header, with spelling checked?
  • Credentials: Are the frontend option, server header, and cookie settings consistent?
  • Errors: Do authentication, validation, rate-limit, and server-error responses include the headers your frontend needs to diagnose the failure?
  • Caching: Is Vary: Origin present when responses differ by origin?
  • Routing: Does the preflight reach the intended service rather than a login page, static server, or CDN edge rule?
  • Environment: Are local, staging, and production origins configured separately?

Keep a small environment matrix in the repository or deployment documentation. Record each frontend origin, API origin, credential requirement, allowed methods, and proxy or CDN behavior. This makes a new deployment easier to compare with the last known-good configuration. For related API tooling and request replay options, see Best API Testing Tools for Developers.

Common mistakes

  • Adding CORS headers only in the frontend: The browser permission is granted by the destination response, not by JavaScript.
  • Using * with credentials: Use a specific approved origin for credentialed requests.
  • Testing only with curl: Command-line success does not bypass browser enforcement in a real frontend.
  • Allowing methods but not headers: A preflight can fail because Authorization or Content-Type is missing even when the method is allowed.
  • Ignoring the OPTIONS route: Authentication or CSRF middleware may reject the preflight before CORS handling runs.
  • Changing several layers at once: Identify whether the application, reverse proxy, CDN, or cache produced the response before editing configuration.
  • Allowing every origin in production: Limit origins to the environments and applications that genuinely need access.

When to revisit

Review this checklist whenever a frontend connects to a new API, a domain or port changes, authentication is introduced, or a request begins failing only after deployment. Recheck it after changing a reverse proxy, CDN rule, API gateway, framework middleware, or cache policy. It is also worth revisiting before a seasonal release or other major planning cycle if infrastructure and environment settings are being updated.

For a practical final pass, reproduce the failing request in the browser, capture the preflight and actual response, run the matching curl test, and compare the deployed headers with your environment matrix. Change one layer at a time, clear or invalidate relevant caches, and retest both an approved origin and an intentionally unapproved origin. If the problem is broader than CORS, check related TLS and deployment behavior with the SSL Certificate Errors guide and the web app deployment checklist.

Related Topics

#CORS#APIs#HTTP#Browser debugging#Web security
T

TeckSite Editorial Team

Web Development Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.