Troubleshoot FastAPI CORS by comparing the browser's preflight with the actual request and response. Record the exact frontend origin, method, requested headers and credential mode before changing the allowlist. A browser's generic CORS message can hide an authentication failure, redirect or server error. Making every origin permissive can obscure the real problem while changing the access contract.
An origin includes the port
https://portal.example.test and https://portal.example.test:8443 are different origins. Scheme changes matter too. Compare the browser's actual Origin header with the configured value rather than comparing only hostnames. Development servers often move ports, so an apparently identical localhost URL can exercise a different allowlist entry. Keep development exceptions scoped to the intended environment.
FastAPI's CORS guide describes preflight OPTIONS requests and ordinary requests with Origin, plus explicit allow-origin configuration. Browser credential behavior needs particular care; use the documented explicit origins, methods and headers for credentialed requests. A successful OPTIONS response is only permission to attempt the actual request, not proof that authentication or the endpoint will succeed.
FastAPI CORS: origins, preflight and middleware behavior
Trace one fictional portal call
Suppose a test portal sends PATCH /profile with Content-Type and Authorization. The browser can first send OPTIONS with Access-Control-Request-Method and Access-Control-Request-Headers. The API must answer the applicable preflight contract. The subsequent PATCH still needs a valid credential and its own CORS response headers. Inspect both network entries, including redirects, rather than focusing only on the final console message.
OPTIONS /profile HTTP/1.1
Origin: https://portal.example.test
Access-Control-Request-Method: PATCH
Access-Control-Request-Headers: authorization,content-typeThe snippet is a synthetic request, not an executed browser capture. Use a disposable endpoint and fictional profile when reproducing it. Compare the same request from the approved origin and a different port. If a command-line HTTP client can read a response while the browser cannot, that difference is consistent with browser CORS enforcement; it does not prove the endpoint's authentication is correct.
| Observation | Likely boundary | Next evidence |
|---|---|---|
| OPTIONS refused | Origin, method or headers | Preflight response |
| OPTIONS passes; PATCH is 401 | Authentication | Actual response contract |
| Redirect before failure | Routing or proxy | Full network chain |
| Only error response unreadable | Middleware/error path | CORS headers on approved-origin error |
Keep authentication errors readable to approved clients
A token can expire between a successful preflight and the real request. If the error response lacks the expected CORS headers, the frontend may see only a network-style failure. Review middleware ordering and outer error handling so approved browser clients can read the intended public error contract. Do not solve that visibility problem by returning protected data or bypassing authentication on OPTIONS-adjacent paths.
Also inspect automatic slash redirects and HTTP-to-HTTPS transitions. A request reaching a different origin or method path after a redirect can change what the browser allows. Fix the canonical API URL and proxy behavior when those are the source of the problem. Adding headers to one application route will not fix a refusal generated by a gateway that answered before the route ran.
Use a small configuration diff and a repeatable check
Change only the origin, method or header actually missing from the intended contract. Repeat the approved-origin request, the unapproved-origin request and a real unauthorized call. Record status, relevant CORS headers and whether application dispatch happened. Avoid logging the Authorization value. Include an ordinary GET as well as the preflighted mutation so middleware behavior is understood on both paths.
No live browser or FastAPI CORS fixture was executed here. The matrix is a proposed diagnostic worksheet for the installed stack. CORS is not general API authentication and does not stop non-browser callers from reaching an endpoint. Keep it as a browser response-access policy alongside actual identity and record authorization. If a release changes middleware or gateway routing, re-run the same small trace before widening permissions further.
Observability for small teams: start with the failed customer task
Bring one API or data workflow and a sanitized failure example for a bounded implementation assessment.
How do you debug CORS in FastAPI?
Compare the exact browser origin and OPTIONS preflight with the actual request, including authentication, redirects and error-response CORS headers.
Does a successful OPTIONS response prove the API call works?
No. The actual request still needs to pass authentication, routing and application validation.
Why does a command-line request work when the browser fails?
Command-line clients are not subject to browser CORS response enforcement; inspect both response headers and the underlying API status.