Dev.to WebDev 🛠 Dev 👁 0 📖 3 min read

My WebSocket worked locally, then died behind Nginx

I built a website that produces configs tested against a real Nginx and Apache server. It's listed on a few launch sites and directories and received a fair amount of feedback. One thing that came up a lot was "WebSocket

I built a website that produces configs tested against a real Nginx and Apache server. It's listed on a few launch sites and directories and received a fair amount of feedback. One thing that came up a lot was "WebSocket works on localhost, but fails behind Nginx" is one of those questions I keep seeing in forums. The page loads, the normal requests work, and the live part just sits there. The answers are usually a pasted config with no reason why.

So I built a small lab with Docker - Nginx 1.30.6 and the older 1.22.1 that Debian 12 ships, a Node backend (ws 8.23.0) and a Python one (websockets 17.4) - and broke it on purpose until I understood every error. And there were a few. Here's what I found.

1. With no WebSocket lines, the backend said 426.

The first config I tested was a plain reverse proxy. Every normal page worked. The WebSocket got back 426 Upgrade Required. In plain words, the app refused a normal HTTP request because it was waiting for a WebSocket handshake.

That error comes from the backend, not Nginx. Nginx doesn't pass the Upgrade and Connection headers along by default, so the app got an ordinary request where it expected a WebSocket handshake. On Nginx 1.22 the Python backend gave me a different error, 505 HTTP Version Not Supported. Same cause, different message. Took me a moment to see that.

2. Adding the headers wasn't enough on older Nginx.

Next I added the two headers and left out proxy_http_version 1.1. On Nginx 1.30 that worked. On 1.22 the Node backend connected, but Python still said 505. It had no idea what I was talking about.

It turns out older Nginx talks HTTP/1.0 to the backend by default, and a WebSocket needs HTTP/1.1. Node let it slide, Python didn't. Since 1.29.7, Nginx uses HTTP/1.1 to the backend by default, which is why the newer version got away with it. Debian 12 and Ubuntu 24.04 still ship older versions, so I keep the line in.

3. Hard-coding Connection "upgrade" leaked into every request.

A lot of copied configs do this:

proxy_set_header Connection "upgrade";

It connects, but my capture showed Connection: upgrade going to the backend on every request, even plain page loads. The map from the Nginx docs fixes it. It sends upgrade only when the browser asks for one, and close otherwise:

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

4. Quiet sockets got cut at exactly 60 seconds.

Once it connected, I left a socket idle. Nginx closed it at exactly 60 seconds, every time. That's the default proxy_read_timeout. I set it to 10 seconds to check, and it closed at 10.

So if your chat or dashboard goes quiet and then drops, it's probably this one. Either raise the timeout for the WebSocket location, or have the app send a ping now and then to know if the door closed on it.

5. The config that passed every test.

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

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 3600s;
    }
}

I ran this config on both Nginx versions with both backends. Every time, the WebSocket connected (101 Switching Protocols), and normal page loads still worked as before. The 3600s timeout is my pick for an hour of quiet; set it to suit your app. The map goes in the http block, outside server.

Check: run sudo nginx -t before you reload. A typo in the map kills the whole reload.

What I did afterwards.

I knew I wasn’t alone, so I put all of this, with the test results for each case, into a guide: Nginx WebSocket proxy not working. I also built the ProxyForge config generator, which has a WebSocket option for reverse proxies (docs).

Anyway, the lesson for the day was this - "it connects" isn't the same as "it's right". Two of the four problems only showed up when I looked at what reached the backend, or waited a full minute.

Which one got you? Or did you hit one I haven't seen yet?

This post was drafted with AI help, edited by me.

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.