Fixing Nginx WebSocket 400 Errors: A Practical Reverse Proxy Guide

The Problem

Everything works perfectly on your local machine. But the moment you deploy behind an Nginx reverse proxy, your real-time features break. Instead of a smooth handshake, the browser console spits out a frustrating error:

WebSocket connection to 'wss://example.com/ws' failed: Error during WebSocket handshake: Unexpected response code: 400

Don't panic. The culprit is usually Nginx's default behavior. It treats every incoming request as standard HTTP traffic. In doing so, it strips out the specific headers your backend needs to keep a persistent connection alive.

The Quick Solution

You need to tell Nginx to pass the Upgrade and Connection headers directly to your backend. Crack open your site configuration file—usually found in /etc/nginx/sites-available/—and update your location block:

location /ws {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;

    # Prevent the 60-second default timeout from killing idle connections
    proxy_read_timeout 86400;
}

Test your syntax and reload the service to apply the changes:

sudo nginx -t
sudo systemctl reload nginx

Why This Happens (The Technical Breakdown)

WebSockets are unique. They start as a standard HTTP request and then "upgrade" to a persistent protocol using two specific headers: Upgrade: websocket and Connection: Upgrade.

Nginx follows the HTTP/1.1 spec strictly. It treats these as "hop-by-hop" headers, meaning it won't pass them from the client to your proxied server unless you explicitly say so. When a Node.js or Go backend receives a WebSocket request without these headers, it assumes the request is malformed. This results in the HTTP 400 Bad Request you're seeing.

Root Cause Identification

The 400 error is a protocol mismatch signal. If your backend logs show a connection attempt that immediately vanishes, Nginx is likely swallowing the handshake headers before they ever reach your application code.

Advanced Configuration for Production Scale

Hardcoding "upgrade" in a location block is fine for one-off fixes. However, if your server handles both standard HTTP and WebSockets, a dynamic mapping is much cleaner. This ensures standard requests keep their keep-alive status while WebSockets get the upgrade they need.

Add this mapping inside the http block of your /etc/nginx/nginx.conf:

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

Now, you can use a more flexible configuration across all your sites:

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

Verification Steps

Check these three things to confirm your fix actually stuck:

- **Inspect the Network Tab:** Open DevTools (F12) and filter by "WS". Your `/ws` request should now show a status of `101 Switching Protocols`.
- **Check Handshake Headers:** Ensure `Request Headers` and `Response Headers` both contain `Upgrade: websocket`.
- **Test via CLI:** Use `wscat` to bypass the browser entirely: `wscat -c wss://example.com/ws`.

Security and Reliability Tips

I’ve learned the hard way that subtle file corruptions during deployment can cause "ghost bugs." When I push Nginx changes to production, I verify the file integrity first. It saves hours of debugging configuration drifts that shouldn't exist.

I use the Hash Generator on ToolCraft to create SHA-256 checksums for my .conf files locally. Because it processes everything in your browser, you aren't uploading sensitive server logic to the cloud just to get a hash.

A Note on Timeouts

Nginx defaults to a 60-second proxy_read_timeout. If your users complain that their chat or dashboard disconnects every minute on the dot, this is why. Bumping this to 86400 (24 hours) keeps the pipe open, but remember to implement a basic ping/pong heartbeat in your app to prune genuinely dead connections.

Key Takeaways

- WebSockets require **HTTP/1.1**; they will fail on 1.0.
- Nginx is a strict gatekeeper that strips hop-by-hop headers by default.
- The 400 error is your backend's way of saying "I don't recognize this as a WebSocket request."