CORS explained, and how to fix the browser error

Access to fetch at 'https://api.example.com/users' from origin 'https://app.example.com'
has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present
on the requested resource.

Cross-Origin Resource Sharing (CORS) is a browser rule. A page served from one origin (scheme + host + port, so https://app.example.com and http://localhost:5173 are different origins) may only read responses from another origin if that server explicitly allows it. The server does so with response headers. The request itself usually reaches the server and gets processed; it is the browser that refuses to hand the response to your JavaScript. That is why curl works and the page does not, and why the fix is always on the server side, never in the frontend code.

What the browser does

• For a simple request (GET, HEAD or POST with a form-style content type and no custom headers) the browser sends it and then checks the response for Access-Control-Allow-Origin. If it is missing or does not match, the response is discarded.
• For anything else (PUT, DELETE, JSON bodies, an Authorization header) the browser first sends a preflight: an OPTIONS request with Access-Control-Request-Method and Access-Control-Request-Headers. The server must answer with the matching Allow- headers and a 2xx status, otherwise the real request is never sent.
• If the request includes cookies or HTTP auth (credentials: 'include'), the server must also send Access-Control-Allow-Credentials: true and may not use * as the allowed origin.

Read the error message

• No ‘Access-Control-Allow-Origin’ header is present: the server did not send the header at all. Often the API framework has a CORS setting that is off, or the proxy in front strips it, or the response was an error page from the proxy (a 502 or 404) that never had the header.
• The ‘Access-Control-Allow-Origin’ header has a value ‘https://other’ that is not equal to the supplied origin: the allow list exists but does not contain this origin. Check the exact scheme, host and port, including www.
• Response to preflight request doesn’t pass access control check: the OPTIONS request failed. Typically the route requires authentication and returns 401 to the preflight, or no route handles OPTIONS at all.
• Request header field authorization is not allowed by Access-Control-Allow-Headers: add that header name to Access-Control-Allow-Headers.
• The value of the ‘Access-Control-Allow-Origin’ header must not be the wildcard ‘*’ when the request’s credentials mode is ‘include’: echo the specific origin instead of *.

Confirm what the server really sends, from a terminal, with the same Origin the browser would use:

curl -sI -H 'Origin: https://app.example.com' https://api.example.com/users | grep -i access-control

curl -sI -X OPTIONS https://api.example.com/users \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: PUT' \
  -H 'Access-Control-Request-Headers: authorization, content-type'

Fix 1: enable CORS in the application

Every web framework has a CORS module. Use it rather than setting headers by hand, because it also handles the preflight and the Vary: Origin header. Allow only the origins you own:

// Express
import cors from 'cors';
app.use(cors({
  origin: ['https://app.example.com', 'http://localhost:5173'],
  credentials: true,
}));

# FastAPI
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com", "http://localhost:5173"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Django uses the django-cors-headers package with CORS_ALLOWED_ORIGINS; Spring has @CrossOrigin and a global CorsConfiguration; Rails uses rack-cors. Make sure the middleware runs before authentication so the preflight is not rejected with 401.

Fix 2: set the headers in the reverse proxy

When you cannot change the application, or want one place for the rule, the proxy can answer the preflight and add the headers. In Nginx:

location /api/ {
    if ($request_method = OPTIONS) {
        add_header Access-Control-Allow-Origin  "https://app.example.com" always;
        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
        add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
        add_header Access-Control-Max-Age 86400 always;
        return 204;
    }
    add_header Access-Control-Allow-Origin "https://app.example.com" always;
    add_header Vary Origin always;
    proxy_pass http://127.0.0.1:8000;
}

always makes Nginx add the header to error responses too, so a 500 from the backend still carries it and the browser shows the real error instead of a CORS error. If the backend already sends its own Access-Control-Allow-Origin, remove one of the two: a response with two values is rejected. Use proxy_hide_header Access-Control-Allow-Origin; to drop the backend’s copy.

In Caddy:

api.example.com {
    @options method OPTIONS
    handle @options {
        header Access-Control-Allow-Origin  "https://app.example.com"
        header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
        header Access-Control-Allow-Headers "Authorization, Content-Type"
        header Access-Control-Max-Age 86400
        respond 204
    }
    header Access-Control-Allow-Origin "https://app.example.com"
    header Vary Origin
    reverse_proxy localhost:8000
}

Fix 3: make it not cross-origin

The cleanest solution is often to avoid the cross-origin hop entirely. Serve the frontend and the API from the same origin and route by path at the proxy, so the page at https://app.example.com calls /api/users on the same host:

app.example.com {
    handle_path /api/* {
        reverse_proxy localhost:8000
    }
    handle {
        root * /var/www/app
        try_files {path} /index.html
        file_server
    }
}

No CORS headers are needed, cookies work without SameSite=None, and there are no preflights, which also makes the app faster. In development, Vite, webpack dev server and Create React App have a proxy setting that does the same thing for localhost.

Mistakes to avoid

• Access-Control-Allow-Origin: * on an API that uses cookies or tokens. The browser will refuse credentialed requests, and if it did not, every website could call your API as the logged-in user.
• Reflecting whatever Origin the request sends, with credentials enabled. That is equivalent to allowing everyone. Check against a list.
• Forgetting Vary: Origin when the allowed origin depends on the request; caches and CDNs may otherwise serve one origin’s header to another.
• Installing a browser extension that disables CORS. It hides the problem on your machine and does nothing for your users.
• Treating a CORS error as the root cause when the backend actually returned 502 or 404. Look at the Network tab: the status code and whether the response has the header tell you which it is.

Official documentation

• Cross-Origin Resource Sharing (CORS) on MDN
• CORS errors reference on MDN
• The CORS protocol in the Fetch standard