Resolving CORS Issues with Nginx Proxy: A Step‑by‑Step Guide and Common Scenarios

When a front‑end site (e.g., http://localhost:8080) requests an API on a different origin (e.g., http://localhost:59200), browsers enforce the CORS policy. The article first ensures the back‑end does not handle CORS and that the API works with tools like Postman.

The CORS problem is solved by adding four response headers via Nginx proxy: Access-Control-Allow-Origin – specifies the allowed origin. Access-Control-Allow-Headers – lists permitted custom request headers. Access-Control-Allow-Methods – lists allowed HTTP methods. Access-Control-Allow-Credentials – indicates whether cookies can be sent.

Typical browsers first send a preflight OPTIONS request; if the required headers are missing, the request is blocked.

Scenario 1

The preflight response lacks Access-Control-Allow-Origin. Adding the header in the Nginx location block fixes the error, but the configuration must include the always flag to ensure the header is sent for all responses.

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

Scenario 2

The preflight OPTIONS request does not receive an HTTP 200/204 status. Adding a conditional block that returns 204 for OPTIONS resolves the issue.

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

Scenario 3

The preflight response is missing the authorization header in Access-Control-Allow-Headers. Adding that header inside the OPTIONS block solves the problem.

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 'authorization';
            return 204;
        }
        proxy_pass http://localhost:59200;
    }
}

Scenario 4

When the API method changes from GET to PUT, the preflight response must include PUT in Access-Control-Allow-Methods and also allow the content-type header.

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 'content-type,authorization';
            add_header Access-Control-Allow-Methods 'PUT';
            return 204;
        }
        if ($request_method != 'OPTIONS') {
            add_header Access-Control-Allow-Origin 'http://localhost:8080' always;
        }
        proxy_pass http://localhost:59200;
    }
}

Scenario 5

If the back‑end already sets CORS headers, adding another Access-Control-Allow-Origin in Nginx can produce duplicate values (e.g., "*, http://localhost:8080"), which browsers reject. The solution is to let either the back‑end or Nginx handle CORS, but not both.

Final Consolidated Configuration

A complete Nginx configuration that covers all cases, using * for headers and methods where appropriate, and enabling credentials only for the trusted origin.

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;
    }
}

By following these steps, developers can reliably resolve CORS errors caused by missing or misconfigured response headers, ensuring smooth communication between front‑end and back‑end services.