If your MinIO setup starts breaking after you put it behind a domain, this guide will help you fix it step by step. MinIO reverse proxy troubleshooting gets much easier when you treat MinIO as a full application stack with DNS, proxy, TLS, console, and S3 API layers instead of only an object storage endpoint.

For the full installation and reverse proxy setup, you can use this guide on Running MinIO Behind a HTTPS Reverse Proxy.

Check the MinIO Stack in Layers

The most common failures after putting MinIO behind a domain are wrong console or API ports, bad Host headers, TLS certificate issues, SignatureDoesNotMatch errors, and uploads that fail in the browser or through S3 clients.

The fastest way to do MinIO reverse proxy troubleshooting is to test layers. Start with MinIO itself, then test the reverse proxy, then test the public domain and browser behavior:

Layer	What to test	Common issue
MinIO service	curl http://127.0.0.1:9000/minio/health/live	Service not running or wrong local port
Reverse proxy	curl -I https://s3.yourdomain.com/minio/health/live	Wrong upstream, missing headers, bad buffering
Console	Open the browser and inspect the Network tab	Redirect loop, wrong console port, broken WebSocket
S3 client	mc admin info, mc ls, upload test	Signature mismatch, TLS trust issue

This layer test is the main reason MinIO reverse proxy troubleshooting becomes easier. You stop guessing and test each part in a clear order.

Verify MinIO Works Locally

Before editing your proxy config, make sure MinIO itself works locally. If MinIO is not healthy on localhost, no reverse proxy fix will solve the problem.

Run these checks:

curl -I http://127.0.0.1:9000/minio/health/live
curl -I http://127.0.0.1:9001
docker ps

A healthy MinIO API should return a valid HTTP response on port 9000, and the console should answer on port 9001 when you use a fixed console address.

If port 9001 is not responding, review your existing setup and make sure the console is pinned with:

--console-address ":9001"

MinIO can use a random console port if you do not set a fixed one, which is a common cause of broken browser redirects after proxying.

1. Fix MinIO Wrong Console and API Port Behavior

One of the most common MinIO reverse proxy troubleshooting cases is when the browser redirects to an internal port or a random port number. That usually means MinIO does not know its public URLs.

Check these environment variables in your current setup:

MINIO_SERVER_URL=https://s3.yourdomain.com
MINIO_BROWSER_REDIRECT_URL=https://console.yourdomain.com

The Server URL tells MinIO what public S3 endpoint clients should use, while Browser Redirect YRL tells the browser where the console lives behind the proxy.

If one of them is missing or wrong, you may see these symptoms:

• Login redirects to http://yourdomain:random-port.
• The console opens, but sends API calls to the wrong place.
• Presigned URLs contain an internal address instead of the public domain.

After changing the values, restart the MinIO container or service and test again in a private browser window.

2. MinIO Reverse Proxy Troubleshooting for 403 Errors

A 403 error after putting MinIO behind Nginx is very often caused by the proxy layer, not by MinIO permissions. This is the part where MinIO reverse proxy troubleshooting needs close attention to headers.

The most important fix is to pass the full Host header:

proxy_set_header Host $http_host;

Do not use this in front of MinIO:

proxy_set_header Host $host;

Using $host can drop the port and change what MinIO receives, which can break S3 signature validation and produce 403 errors even with valid credentials.

Another important fix is:

proxy_cache_convert_head off;

This prevents a proxy cache from converting HEAD requests into GET requests, which can cause MinIO to reject the request because the method no longer matches the signed request.

For the S3 API server block, these settings are usually the safe baseline:

ignore_invalid_headers off;
client_max_body_size 0;
proxy_buffering off;
proxy_request_buffering off;
chunked_transfer_encoding off;
proxy_http_version 1.1;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_convert_head off;

This set of directives is important because MinIO reverse proxy troubleshooting is about preserving the original request exactly as MinIO expects it.

3. Fix MinIO SignatureDoesNotMatch Errors

If uploads or bucket operations fail with SignatureDoesNotMatch, your first suspect should be the proxy headers or the public endpoint URL. This is one of the most common MinIO reverse proxy troubleshooting problems with presigned URLs and SDK uploads.

Common causes include:

• Host header changed by the proxy.
• Public endpoint in MinIO does not match the real domain clients use.
• The request path is different from what the client signed.
• Protocol mismatch, such as generating a URL for HTTP but using HTTPS later.

First, test with the mc client:

mc alias set myminio https://s3.yourdomain.com ACCESS_KEY SECRET_KEY
mc admin info myminio
mc ls myminio

If the info works but uploads fail, that often points to a request-handling issue in the proxy or the app that generates presigned URLs.

Also, test with curl:

curl -v http://127.0.0.1:9000/minio/health/live
curl -v https://s3.yourdomain.com/minio/health/live

Compare the local and public behavior. If local works and the domain fails, the problem is always in the reverse proxy, DNS, or TLS layer rather than in MinIO itself.

This is another place where MinIO reverse proxy troubleshooting is about comparing what the client sends with what MinIO finally receives.

4. Fix MinIO TLS and Certificate Problems

TLS issues show up in different ways depending on the client. Browsers show warnings, mc may return an x509 trust error, and curl may complain about the certificate chain or hostname mismatch.

Check the live certificate like this:

openssl s_client -connect s3.yourdomain.com:443 -servername s3.yourdomain.com </dev/null 2>/dev/null | openssl x509 -noout -text | grep -E "Subject:|DNS:|Not After"

Make sure the certificate covers the exact subdomain you use for MinIO. A certificate for only the root domain is not enough for s3.yourdomain.com unless the certificate includes that hostname.

For production, use a trusted CA such as Let’s Encrypt through your reverse proxy layer. Self-signed certificates often break browser uploads, CLI clients, and SDK connections unless you manually bypass verification, which is not a good production setup.

This part matters because MinIO reverse proxy troubleshooting is not only about getting HTTPS to load in a browser. It also needs S3 clients, SDKs, and presigned requests to trust the endpoint consistently.

5. Fix MinIO Broken Browser Uploads and Large File Failures

If small uploads work but large uploads hang or fail, the reverse proxy is usually buffering too much or enforcing limits that MinIO does not want.

You can use these directives in the S3 API server block:

client_max_body_size 0;
proxy_buffering off;
proxy_request_buffering off;
chunked_transfer_encoding off;
proxy_connect_timeout 300;
proxy_read_timeout 300;
proxy_send_timeout 300;

These settings reduce the chance of large object uploads hanging, timing out, or failing before the request reaches MinIO.

Test uploads in three ways:

• Upload with the MinIO console in the browser and watch the Network tab.
• Upload with mc cp to confirm CLI behavior.
• Upload through your application or presigned URL flow to confirm the real production path.

Open browser DevTools and inspect failed requests closely. A 413 error points to body size limits, a 502 or 504 points to proxy timeout behavior, and a 403 during upload can still be a signature or Host header problem.

This is why MinIO reverse proxy troubleshooting should include both CLI and browser testing, not only one of them.

6. Fix a Blank or Broken MinIO Console

If the MinIO console loads partially, stays blank, or keeps reconnecting, check WebSocket support in the console proxy block. The console depends on WebSocket traffic for live updates and UI behavior.

Use these settings for the console location block:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Proto $scheme;

Then open the browser developer tools, go to Network, filter by WS, and inspect whether the WebSocket handshake succeeds. A valid WebSocket upgrade usually returns a 101 Switching Protocols response.

Check MINIO_BROWSER_REDIRECT_URL again if the console keeps bouncing between addresses. A wrong console URL can make the interface appear broken even when the reverse proxy itself is correct.

Simple Verification Commands

After every change, run a small test set rather than changing everything at once. This helps MinIO reverse proxy troubleshooting stay clean and predictable:

curl -I http://127.0.0.1:9000/minio/health/live
curl -I https://s3.yourdomain.com/minio/health/live
mc alias set myminio https://s3.yourdomain.com ACCESS_KEY SECRET_KEY
mc admin info myminio
mc ls myminio
sudo nginx -t
sudo tail -f /var/log/nginx/error.log

If local health works, public health works, mc admin info works, and Nginx has no config errors, the stack must be healthy.

Troubleshooting Checklist

You can use this list when you need a fast review during MinIO troubleshooting:

• MinIO is healthy on localhost port 9000.
• The console is fixed to port 9001.
• MINIO_SERVER_URL matches the public S3 endpoint.
• MINIO_BROWSER_REDIRECT_URL matches the console domain.
• Nginx passes Host $http_host to MinIO.
• proxy_cache_convert_head off is enabled.
• Buffering is disabled for uploads.
• TLS certificate matches the real subdomain.
• Console WebSocket headers are present.
• Browser DevTools and Nginx logs show clean requests.

A good production option for stronger network and disk performance is a powerful dedicated server, especially when your MinIO stack handles large files or heavy object storage traffic.

Conclusion

MinIO reverse proxy troubleshooting becomes much easier when you stop treating MinIO like only an S3 endpoint and start treating it like a layered application stack. Most real problems come from a small group of issues, including wrong console URL, wrong Host header, TLS mismatch, proxy buffering, or a broken WebSocket path.

If you still need a domain for the setup, you can register a domain at PerLod and point it to your MinIO server with the correct DNS records.

We hope you enjoy this guide.

To understand why MinIO signature errors happen when the Host header or request path changes, you can check the AWS Signature V4 docs.

FAQs