Resolving CORS Issues with Nginx Proxy Configuration: A Step‑by‑Step Guide

When you encounter cross‑origin (CORS) problems, do not immediately copy random solutions; read this comprehensive guide first, as it explains the underlying principles and shows how to fix them using Nginx.

Preparation : the front‑end runs at http://localhost:8080 and the back‑end service at http://localhost:59200. Ensure the back‑end does not already set CORS headers, and verify the API works with Postman before adding any proxy.

The four CORS response headers that must be returned are: Access-Control-Allow-Origin – specifies the allowed origin. Access-Control-Allow-Headers – lists permitted custom request headers (checked only on pre‑flight). Access-Control-Allow-Methods – lists allowed HTTP methods (checked only on pre‑flight). Access-Control-Allow-Credentials – indicates whether cookies can be sent with cross‑origin requests.

Many tutorials suggest simply adding these headers in Nginx, which works for most cases, but some configurations still produce errors because the pre‑flight request does not receive the required headers.

Understanding the pre‑flight request : When the browser detects a cross‑origin request, it first sends an OPTIONS request to verify that the server permits the origin, method, and headers. If the server’s response lacks the necessary headers, the actual request is blocked.

Typical error cases and Nginx fixes :

Case 1 – Missing Access-Control-Allow-Origin:

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

Case 2 – Pre‑flight request does not return HTTP 200/204:

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

Case 3 – Missing Access-Control-Allow-Headers for authorization:

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

Case 4 – Need to allow additional methods such as PUT:

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

Case 5 – Duplicate Access-Control-Allow-Origin values (e.g., "*" and a specific domain) cause a conflict; keep only the specific domain header.

Final robust configuration (choose one style):

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;
        }
        add_header Access-Control-Allow-Origin 'http://localhost:8080' always;
        add_header Access-Control-Allow-Credentials 'true' always;
        proxy_pass http://localhost:59200;
    }
}

The guide concludes that you should either let the back‑end handle CORS or let Nginx handle it, but not both, to avoid contradictory configurations.

By following the step‑by‑step examples and adjusting the headers to match your actual API requirements, you can reliably eliminate CORS errors in your development environment.