Fix CORS Errors with Nginx Proxy: A Step‑by‑Step Guide

When a front‑end site (e.g., http://localhost:8080) accesses a back‑end API ( http://localhost:59200) without proper CORS handling, the browser blocks the request. First ensure the back‑end does not already set CORS headers and verify the API works with tools like Postman.

Key CORS response headers

Access-Control-Allow-Origin – specifies allowed origin(s).

Access-Control-Allow-Headers – lists permitted custom request headers (checked only on preflight).

Access-Control-Allow-Methods – lists allowed HTTP methods (checked only on preflight).

Access-Control-Allow-Credentials – indicates whether cookies can be sent; must be true only when needed.

A preflight (OPTIONS) request is sent by the browser to confirm that the server permits the origin, method, and headers before the actual request is made.

Testing the Nginx proxy

Configure Nginx to listen on port 22222 and proxy to the back‑end:

server {
    listen 22222;
    server_name localhost;
    location / {
        proxy_pass http://localhost:59200;
    }
}

After confirming the proxy works, attempt the front‑end request and observe the CORS error.

Case 1 – Missing Access‑Control‑Allow‑Origin

The error shows no Access-Control-Allow-Origin header. Add it in the Nginx location block and test again:

server {
    listen 22222;
    server_name localhost;
    location / {
        add_header Access-Control-Allow-Origin 'http://localhost:8080';
        proxy_pass http://localhost:59200;
    }
}

If the error persists, the always flag may be required:

add_header Access-Control-Allow-Origin 'http://localhost:8080' always;

Case 2 – Preflight request returns non‑200 status

The OPTIONS request must return a successful status (commonly 204). Update the config:

if ($request_method = 'OPTIONS') {
    return 204;
}

Case 3 – Missing Access‑Control‑Allow‑Headers

If the request includes a custom header like Authorization, add it to the preflight response:

if ($request_method = 'OPTIONS') {
    add_header Access-Control-Allow-Headers 'authorization';
    return 204;
}

Case 4 – Unsupported HTTP method

When using a method such as PUT, extend Access-Control-Allow-Methods:

add_header Access-Control-Allow-Methods 'PUT';

Case 5 – Duplicate Access‑Control‑Allow‑Origin values

If both Nginx and the back‑end set Access-Control-Allow-Origin, only one value is allowed. Choose either Nginx or the application to handle CORS, but not both.

Final recommended configuration

server {
    listen 22222;
    server_name localhost;
    location / {
        if ($request_method = 'OPTIONS') {
            add_header Access-Control-Allow-Origin 'http://localhost:8080';
            add_header Access-Control-Allow-Headers '*';
            add_header Access-Control-Allow-Methods '*';
            add_header Access-Control-Allow-Credentials 'true';
            return 204;
        }
        if ($request_method != 'OPTIONS') {
            add_header Access-Control-Allow-Origin 'http://localhost:8080' always;
            add_header Access-Control-Allow-Credentials 'true';
        }
        proxy_pass http://localhost:59200;
    }
}

This setup ensures the preflight request receives the required headers and status, while normal requests get the origin and credential headers, effectively solving most CORS problems encountered during development.