CORS Error Fix Playbook (Preflight / Origin / Credentials)

Quick Triage

• -Classify semantics first: distinguish preflight OPTIONS failure, origin allowlist mismatch, and credential-rule violation from non-CORS backend errors.
• -Capture one failing request with `request_id`, `Origin`, method, `Access-Control-Request-Method`, `Access-Control-Request-Headers`, credentials mode, and `Access-Control-*` response headers before changing config.
• -Determine whether the incident is preflight route handling failure, origin policy mismatch, or credentialed-request policy mismatch.

Execution Steps

1. 1Reproduce one browser CORS failure and preserve request ID, route, origin, method, and response headers.
2. 2Confirm preflight handling by sending OPTIONS to the same route and checking a successful response with required allow headers.
3. 3Validate origin policy by matching `Access-Control-Allow-Origin` to an explicit allowlist entry for the caller origin.
4. 4Check `Access-Control-Allow-Credentials` alignment with the request credentials mode.
5. 5Check cookie `SameSite` and `Secure` attributes plus `Authorization` header usage for credentialed cross-origin requests.
6. 6Compare CDN, gateway, and app-layer CORS configs and validate cache behavior with `Vary: Origin`.
7. 7Apply minimal header and allowlist fixes for the exact origin-route-method tuple, retest, and remove temporary permissive wildcard rules.

Diagnosis Dimensions

• -Protocol semantics: preflight `OPTIONS` negotiation failure versus origin allowlist mismatch versus credential-policy mismatch.
• -Enforcement boundary: browser CORS enforcement versus server, gateway, and CDN responsibility for correct CORS headers and route behavior.
• -Scope alignment: caller origin scheme-host-port and target route version matching required allowlist, method, and request-header policy.
• -Safety guardrails: least-exposure origin and credentials settings that prevent wildcard overexposure and preserve intentional access boundaries.

Verify Recovery

• -Replay the original failing flow and confirm browser success only for the intended origin, method, and headers.
• -Verify a disallowed origin still returns blocked CORS behavior, proving controls were not over-broadened.
• -Observe CORS failure rate by route, origin, and reason for at least one sustained traffic window after rollout.

What To Avoid

• -Avoid enabling global wildcard origin before isolating the failing route and request mode.
• -Avoid changing auth or business logic when preflight routing or CORS headers cause the failure.
• -Avoid ignoring gateway or CDN header mutation while debugging only application middleware.
• -Avoid keeping permanent wildcard or broad allow-header policies after incident mitigation.

Pro Tip

Frequently Asked Questions

Official References

• -WHATWG Fetch Standard: HTTP CORS Protocol
• -RFC 6454: The Web Origin Concept
• -AWS API Gateway: CORS for REST APIs
• -Azure API Management: CORS Policy
• -Google Cloud Storage: Cross-Origin Resource Sharing