CORS Debugging Workflow: Origins, Preflight, Headers, Credentials.

A reliable CORS debugging workflow starts with the browser’s exact origin, method, headers, and credentials mode. Determine whether the failure occurred during the OPTIONS preflight or on the actual request, then compare that transaction with the server policy. Fix the narrow mismatch and retest through the real browser path. Do not start by allowing every origin.

CORS is a browser enforcement protocol, not a replacement for authentication or authorization. A command-line client can receive a response that browser JavaScript is forbidden to read. Keep production cookies, tokens, customer data, and private response bodies out of screenshots, tickets, and test logs. Use approved test accounts and redacted evidence.

Start With The Browser Contract

Open the failing page in a normal browser session and preserve one reproducible request in the Network panel. Record the page URL, request URL, method, request headers set by application code, content type, credentials mode, response status, and console message. Capture whether an OPTIONS request appears immediately before the application request.

This evidence prevents a common category error: changing server CORS headers when the browser is actually reporting a redirect, DNS problem, TLS failure, blocked mixed content, service-worker response, or application exception. Use the Fetch API error handling guide to separate transport, HTTP, parsing, and application failures after CORS access succeeds.

Confirm The Two Origins

An origin is the scheme, host, and port tuple. Paths do not create different origins, but http and https do, as do example.com and api.example.com, or ports 3000 and 3001. Write the requesting origin and target origin side by side before reviewing policy.

Check the browser-supplied Origin request header instead of reconstructing it from memory. Include development, preview, and production origins explicitly in the environment policy. Do not confuse a URL allowlist with an origin allowlist: an origin has no path, query, or fragment.

Decide Whether Preflight Is Expected

The browser can send some cross-origin requests directly, but requests outside the CORS-safelisted method and header constraints require a preflight. JSON POST requests, custom headers, Authorization, PUT, PATCH, and DELETE commonly trigger OPTIONS. The Fetch Standard defines this decision and the CORS-preflight fetch algorithm.

Do not optimize away a legitimate preflight before correctness is established. A preflight is a permission check for the intended method and header names. First prove why the request is preflighted, then decide whether the API contract genuinely needs those features.

Inspect The OPTIONS Request

Select the OPTIONS entry and verify its URL, Origin, Access-Control-Request-Method, and Access-Control-Request-Headers. The advertised method and header names must match the actual request the browser intends to send. Check whether a service worker, frontend proxy, CDN, load balancer, or framework route changed the target.

Classify the outcome precisely. No OPTIONS entry suggests the request did not require preflight or failed earlier. A network error points to transport or routing. A 301 or 302 exposes redirect behavior. A 401 or 403 often means authentication middleware intercepted OPTIONS. A 404 or 405 means the route or method is not handled.

Validate The Preflight Response

A successful status is not enough. The response must authorize the requesting origin, intended method, and requested non-safelisted headers. Compare Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Headers with the captured request. Header-name comparison is case-insensitive, but policy generators and tests should still use consistent spelling.

The browser reports a CORS failure when authorization headers are absent, malformed, duplicated incorrectly, or narrower than the request. The MDN CORS guide documents the request and response headers and provides representative preflight exchanges. Treat it as protocol evidence, not a reason to copy a wildcard configuration.

Inspect The Actual Response

After preflight succeeds, inspect the application request separately. The actual response also needs a valid Access-Control-Allow-Origin value. CORS headers added only to OPTIONS do not make the GET, POST, or error response readable. Verify success and failure statuses because exception handlers frequently bypass normal middleware.

Confirm that the expected application request was sent. If it was not, the preflight still failed. If it was sent but JavaScript cannot read the response, inspect the actual response headers, status, and redirect chain. Expose only response headers the frontend must read through Access-Control-Expose-Headers.

Handle Credentials Deliberately

Decide whether the request uses cookies, HTTP authentication, or TLS client identity. In fetch, cross-origin credentials normally require credentials: include. The server must opt in with Access-Control-Allow-Credentials: true and an explicit allowed origin. A wildcard origin cannot authorize a credentialed browser response.

CORS does not override cookie rules. Secure, SameSite, domain, path, expiry, and third-party cookie restrictions can prevent a cookie from being sent even when CORS headers are correct. Inspect the request’s Cookie behavior through browser tools without copying cookie values into logs.

Check Redirects And Error Paths

Inspect every response in the chain. An API route may redirect from http to https, add a trailing slash, send an unauthenticated request to a login page, or route an expired session to another host. The redirect destination needs to be valid for the browser request, and middleware must not convert OPTIONS into an authentication redirect.

Test a deliberate validation failure, unauthorized response, not-found response, and server error. Apply CORS policy consistently where the browser must read those responses. Do not leak private error details merely to make an error body readable.

Account For Proxies And Middleware

Map where CORS headers are produced: application framework, reverse proxy, API gateway, CDN, serverless platform, or edge function. Multiple layers can emit conflicting Access-Control-Allow-Origin values or strip Vary. Choose one policy owner when possible and document exceptions.

Compare the direct application response with the public endpoint only in an approved environment. Check route ordering so OPTIONS reaches the CORS handler before authentication, CSRF, body parsing, or business logic. Confirm the public host forwards Origin and does not cache an upstream response under an incomplete key.

Test Dynamic Origin Allowlisting

For a private or credentialed API, compare the incoming Origin with an exact allowlist and return that origin only when authorized. Normalize configuration inputs, but do not use substring matching, suffix matching without a label boundary, or blindly reflect any Origin value. Reject null unless the use case has been assessed explicitly.

Test one approved origin and several near misses: wrong scheme, wrong port, lookalike subdomain, appended attacker domain, and an unlisted preview host. The response for a rejected origin should omit permission rather than returning a misleading wildcard.

Verify Cache Separation

When Access-Control-Allow-Origin changes according to the request Origin, send Vary: Origin so caches distinguish variants. RFC 9111 requires caches to incorporate nominated Vary fields when selecting a stored response. Without correct separation, one origin can receive headers generated for another.

Inspect browser, CDN, gateway, and reverse-proxy cache behavior. Purge stale variants after policy changes where required. Review Access-Control-Max-Age independently: it controls preflight-result reuse, while ordinary HTTP caching controls stored responses. Use the HTTP cache headers checklist for the broader cache contract.

Reproduce With A Controlled Request

Create a minimal browser page or automated browser test that uses the same origin, method, headers, and credentials mode. Command-line tools are useful for inspecting server responses, but they do not enforce browser CORS. When simulating preflight, send Origin, Access-Control-Request-Method, and Access-Control-Request-Headers explicitly.

Store redacted request definitions, expected status, and expected CORS headers in the team’s API testing workspace. Keep browser verification in the acceptance path so a passing curl command cannot mask a browser failure.

Avoid Unsafe Shortcuts

Do not disable browser security, install an unreviewed CORS extension, route production traffic through a public proxy, or add Access-Control-Allow-Origin: * to a private API. These actions bypass evidence or expand who can read responses. They do not repair authentication, authorization, or route ownership.

Do not accept arbitrary Origin values and echo them with credentials. Do not add CORS headers only on the frontend hosting service when the API response is the blocked resource. Do not treat a hidden console error as a fix; verify the browser can complete the intended workflow and that an unapproved origin still fails.

Build A Regression Matrix

Cover approved and rejected origins, simple and preflighted requests, each supported method, required custom headers, credentialed and non-credentialed modes, success and error responses, redirects, and cache hits. Include development, preview, and production configurations without sharing production secrets.

Assertions should verify status, allowed origin, credentials flag, allowed methods and headers, Vary behavior, and readable response data. Add negative tests for wildcard credentials, reflected hostile origins, missing OPTIONS handling, duplicated headers, and stale cached variants.

Define Release Evidence

A CORS fix is ready when the original browser workflow passes, the narrow policy is documented, unapproved origins fail, credentials follow the intended cookie rules, error responses remain controlled, cache variants are separated, and tests run against the public delivery path. Record the configuration owner and rollback procedure.

Block release when the team cannot explain the requesting origin, preflight behavior, policy layer, credential model, or cache key. The Full Stack Web Development course can provide structured practice across frontend requests, backend APIs, authentication, deployment, and the debugging evidence this workflow depends on.

FAQ

Why does a request work in curl but fail in the browser?

Curl does not enforce browser CORS. Compare the browser Origin, preflight, credentials mode, redirects, and response headers instead of treating the curl response as proof of browser permission.

Can Access-Control-Allow-Origin use a wildcard with cookies?

No. A credentialed browser response requires an explicit allowed origin and Access-Control-Allow-Credentials: true.

Should an OPTIONS preflight require user authentication?

Normally the preflight itself carries no user credentials. Route it through the CORS policy before middleware that requires the application session, while still authorizing only the intended origin, method, and headers.