Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

The MinIO Console will not work behind an nginx proxy: no login, 403 on the WebSocket, or repeated disconnects

ErrorWebSocket upgrade requests rejected with HTTP 403 (browser developer tools, request to /api/v2/objectManager)

Short answer

Behind a proxy the MinIO Console needs three things. MINIO_BROWSER_REDIRECT_URL must be the public address the browser uses, or WebSocket upgrades get a 403. The proxy must forward Upgrade headers. And the proxy timeout must be long. Also send the Console and the S3 API to separate upstreams, never one.

  • Applies to nginx 1.26, Docker Compose v2, MinIO Console
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the browser developer tools on the Console page, go to the Network tab, filter by WS, and reload. The status of the WebSocket request shows which cause below applies: 403 means the redirect URL, no WebSocket request or a failed upgrade means the nginx headers, a connection that dies after a minute means the timeout.

    docker compose logs --tail 50 minio
    sudo tail -n 30 /var/log/nginx/error.log
  2. 2Match what you see, then jump to its fix

    1. 1The WebSocket request to the Console is rejected with HTTP 403, or the Console works on its own port but not through the proxyMINIO_BROWSER_REDIRECT_URL is missing or is not the public addressFix
    2. 2The WebSocket request in the Network tab fails or never switches protocols, while ordinary page requests worknginx does not forward the WebSocket upgradeFix
    3. 3Login works, then the UI disconnects again and again, about a minute after the last activityThe proxy closes the idle WebSocket after its default timeoutFix
    4. 4The proxied address does not show the Console login page at all, while the Console's own port doesThe Console and the S3 API share one locationFix

What does the error look like?

  • WebSocket upgrade requests rejected with HTTP 403 (browser developer tools, request to /api/v2/objectManager)
  • The Console UI shows repeated disconnects

Cause 1 of 4

MINIO_BROWSER_REDIRECT_URL is missing or is not the public address

1Check

MinIO's documentation says that when the Console is served only through a reverse proxy, this variable must hold the hostname the proxy manages. Without it the Console answers on any address, and a request that arrives with an origin that does not match is rejected. The documented symptom is a 403 on WebSocket upgrades.

docker compose config | grep -n MINIO_BROWSER_REDIRECT_URL

2Fix

Set the variable on the MinIO container to the exact public URL that people type in the browser, and recreate the container.

services:
  minio:
    # keep your existing image, command and volumes
    environment:
      MINIO_BROWSER_REDIRECT_URL: https://console.example.com

3Verify

Reload the Console and confirm that the WebSocket request is no longer 403.

docker compose up -d minio

Confirmed by docs.min.io

Did this fix it?

Cause 2 of 4

nginx does not forward the WebSocket upgrade

1Check

The Console talks over WebSocket on paths such as /api/v2/objectManager. nginx's own WebSocket guide sets the Upgrade and Connection headers by hand, so a location without them does not complete the upgrade. Look for proxy_set_header Upgrade in the location that serves the Console.

sudo nginx -T 2>/dev/null | grep -n -i -E 'upgrade|proxy_pass'

2Fix

Pass both headers on to the Console. On nginx before 1.29.7, also set the proxy HTTP version to 1.1.

http {
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }

    server {
        server_name console.example.com;

        location / {
            proxy_pass http://minio:9001;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
        }
    }
}

3Verify

Test the configuration, reload nginx, and look at the WebSocket request again: it should show status 101.

sudo nginx -t && sudo systemctl reload nginx

Confirmed by nginx.org

Did this fix it?

Cause 3 of 4

The proxy closes the idle WebSocket after its default timeout

1Check

nginx closes a proxied WebSocket if the server sends no data for 60 seconds, which is the default of proxy_read_timeout. MinIO's documentation warns that without a long tunnel timeout the connections are killed after the regular HTTP timeout and the UI shows repeated disconnects.

sudo nginx -T 2>/dev/null | grep -n proxy_read_timeout

2Fix

Raise proxy_read_timeout in the Console location.

location / {
    proxy_pass http://minio:9001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_read_timeout 1h;
}

3Verify

Reload nginx, keep the Console open for several minutes and watch the connection stay up.

sudo nginx -t && sudo systemctl reload nginx

Confirmed by docs.min.io

Did this fix it?

Cause 4 of 4

The Console and the S3 API share one location

1Check

The S3 API and the Console run on separate ports, so each needs its own route or host name in the proxy. MinIO's own examples put the Console on port 9001. A proxy_pass that points at the API port serves the API, not the login page.

sudo nginx -T 2>/dev/null | grep -n -E 'server_name|proxy_pass'

2Fix

Give the Console its own server block or path, as in the examples above, and keep the API on its own host name pointing at the API port.

# console.example.com -> Console port
proxy_pass http://minio:9001;

# s3.example.com -> the S3 API port of the same container
# proxy_pass http://minio:<api-port>;

3Verify

The Console host name now shows the login page.

curl -sI https://console.example.com/ | head -n 1

Confirmed by docs.min.io

Did this fix it?

How do I stop it coming back?

  • Give the Console and the S3 API different host names. It keeps the redirect URL and the proxy rules simple.
  • Set MINIO_BROWSER_REDIRECT_URL in the compose file from the start, and change it whenever the public address changes.
  • Keep the WebSocket headers and a long proxy_read_timeout in every nginx server block that fronts the Console.
  • After any change, test with the browser Network tab, filtered by WS.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.