Skip to content

CORS Error Handling

CORS Error Handling

Overview

This page documents the current CORS behavior for the FastAPI app and the Docker/Vite dev stack.

The main point: a browser CORS error can still be caused by a server-side failure if the error response does not include CORS headers.

Current Behavior

The API adds CORS headers to normal responses and error responses so the browser can surface the real backend failure instead of a misleading CORS message.

The dev frontend also relies on relative URLs and a Vite proxy, so requests stay on the dev origin rather than going directly to the API container.

Proxy Rules

When working in the Docker/Vite dev stack:

  • use relative API URLs from the frontend
  • proxy /api/v1 and /static to the API container
  • enable redirect following in the proxy when upstream endpoints return 307s

See API URL Handling for the trailing-slash side of that setup.

Backend Middleware

The backend applies a CORS middleware layer that ensures headers are present on successful responses and on exceptions.

That keeps browser errors readable when the real problem is a server exception rather than an origin mismatch.

Testing

  • trigger a backend error and confirm the browser shows the real error
  • verify the response still includes Access-Control-Allow-Origin
  • confirm the dev proxy is only using relative URLs

Troubleshooting

  • If you see a browser CORS error, inspect the backend logs first.
  • If requests are going to the wrong origin, check the frontend client URL construction.
  • If redirects break requests, check the Vite proxy settings and trailing-slash handling.