Debug Common CORS Errors

Debugging CORS Errors Step by Step

CORS errors appear in the browser console but the actual response is hidden from JavaScript for security reasons. Here is how to diagnose them systematically.

Step 1: Read the Error Message

Error Message	Likely Cause
"No 'Access-Control-Allow-Origin' header"	Server is not sending CORS headers at all
"must not be the wildcard '*' when credentials"	Origin is * but client uses credentials: include
"is not in the list of allowed origins"	Origin mismatch (check protocol, port, trailing slash)
"Method PUT is not allowed"	Missing method in Access-Control-Allow-Methods
"Request header field X-Api-Key is not allowed"	Missing header in Access-Control-Allow-Headers

Step 2: Inspect the Network Tab

1. Open DevTools > Network.
2. Find the OPTIONS request (if present). Check its status code and response headers.
3. Find the actual request (GET/POST/etc). Check if Access-Control-Allow-Origin is in the response headers.
4. Verify the Origin request header matches what the server expects.

Step 3: Test with curl

curl -v -X OPTIONS \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type, Authorization" \
  https://api.example.com/data

This shows you exactly what headers the server returns without browser interference.

Step 4: Check Common Issues

• Protocol mismatch: http:// vs https:// — the origin must match exactly.
• Port mismatch: localhost:3000 vs localhost:8080 — different ports are different origins.
• Trailing slash: https://example.com vs https://example.com/ — some servers are strict.
• Subdomain: www.example.com vs example.com — these are different origins.
• Middleware order: CORS middleware must run before auth middleware.
• Reverse proxy stripping headers: Check if your proxy (Nginx, CloudFront, ALB) is removing CORS headers.

Step 5: Verify the Fix

After applying the fix, hard-refresh the browser (Ctrl+Shift+R) to clear the preflight cache and test again.