The MinIO Console will not work behind an nginx proxy: no login, 403 on the WebSocket, or repeated disconnects
WebSocket 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.
Fix it fast
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.log2Match what you see, then jump to its fix
- 1
The 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
The WebSocket request in the Network tab fails or never switches protocols, while ordinary page requests worknginx does not forward the WebSocket upgradeFix - 3
Login 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
The 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
- 1
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_URL2Fix
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.com3Verify
Reload the Console and confirm that the WebSocket request is no longer 403.
docker compose up -d minioConfirmed by docs.min.io
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 nginxConfirmed by nginx.org
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_timeout2Fix
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 nginxConfirmed by docs.min.io
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 1Confirmed by docs.min.io
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
Related fixes
Servers
nginx 502 Bad Gateway in front of a Node.js app
connect() failed (111: Connection refused) while connecting to upstream
A 502 means nginx reached for your Node.js app and got nothing usable back.
5 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
Docker php image has no php.ini and my edits do not stay
A setting changed in php.ini inside the container is gone after the container is recreated
The official php image ships php.ini-development and php.ini-production but no active php.ini.
2 causes, each with a fixServers
nginx returns 403 and logs directory index is forbidden
directory index of "/usr/share/nginx/html/" is forbidden
nginx got a request for a folder, found none of the index files it was told to look for, and listing the folder is off by default.
3 causes, each with a fixServers
nginx in a container returns 502 with 'connection refused' to another container
502 Bad Gateway
Inside a container, localhost is the container itself.
4 causes, each with a fixServers
The nginx container serves the default page or 404 because /usr/share/nginx/html has no app files
requests for your pages return 404 Not Found
The official nginx image serves whatever sits in /usr/share/nginx/html.
3 causes, each with a fix