Nginx WebSocket proxy not working: 426, 505 and 60-second drops
Updated 14 November 2026 · By Brent Alexis
Short answer: Nginx doesn't pass a browser's WebSocket request on to your app unless you tell it to. Add proxy_set_header Upgrade $http_upgrade; and a Connection header to the location, and on Nginx older than 1.29.7 also proxy_http_version 1.1;. Without them, apps answer 426 Upgrade Required or 505 HTTP Version Not Supported. If the connection works but drops after a minute of quiet, that's Nginx's 60-second proxy_read_timeout.
Tested on the official nginx Docker image (Nginx 1.30.6), Debian 12's Nginx 1.22.1 and Debian 12's Apache 2.4.71, against two real WebSocket servers (Python websockets 17.4 and Node ws 8.23.0) and a small test app that reports what it receives: 17 checks. How it's tested
- The config that works
- What each missing line does
- Why Nginx 1.30 forgives a missing line
- Connection "upgrade" or the map?
- Disconnects after 60 seconds
- Apache
- Behind Cloudflare
- Check it works
The config that works
This is the form ProxyForge's Config Generator writes when you tick WebSockets. It worked on both Nginx versions with both WebSocket servers.
# Outside any server block (in the http context, e.g. at the top of the site file)
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
# ...
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;
}
}
Nginx's documentation explains why the extra lines are needed: Upgrade is a hop-by-hop header, so it “is not passed from a client to proxied server.” You have to set it, and the matching Connection header, yourself.
What each missing line does
Each row is the response the browser's WebSocket handshake got back through Nginx. 101 Switching Protocols means it worked.
| What's in the location | Nginx 1.30.6 | Nginx 1.22.1 (Debian 12) |
|---|---|---|
Only proxy_pass | 426 Upgrade Required | 426 (Node), 505 HTTP Version Not Supported (Python) |
Upgrade and Connection headers, no proxy_http_version 1.1 | 101, works | 101 (Node), 505 (Python) |
Connection header but no Upgrade header | Treated as a normal request (200, test app) | Treated as a normal request (200, test app) |
| All three lines | 101 | 101 |
In the browser, both errors look the same: the WebSocket fails to open, and some libraries, such as Socket.IO, can quietly fall back to slower polling. The status code is how you tell them apart. 426 means the app never saw the upgrade request; 505 means it saw it over HTTP/1.0, which WebSockets can't use.
Why Nginx 1.30 forgives a missing line
Until version 1.29.7, Nginx spoke HTTP/1.0 to the app, and the WebSocket handshake needs HTTP/1.1. Since 1.29.7 (March 2026), Nginx's own blog says it uses “HTTP/1.1 with keep-alive” by default, so 1.30 and newer work without proxy_http_version 1.1. The lab showed the difference directly: a normal request reached the app as HTTP/1.1 from Nginx 1.30.6 but as HTTP/1.0 with Connection: close from Debian 12's 1.22.1.
Distro packages are older than that: Debian 12 ships 1.22 and Ubuntu 24.04 ships 1.24 (see the http2 guide for each distro's version). Whether the missing line breaks things there depends on your app's WebSocket library: Node's ws accepted the HTTP/1.0 request, Python's websockets refused it. Keep proxy_http_version 1.1; in the config. It costs nothing and works everywhere.
Connection "upgrade" or the map?
Many examples use proxy_set_header Connection "upgrade"; instead of the map. It works for WebSockets, but it sends Connection: upgrade to your app on every normal request too. With the map, the app got Connection: close on normal requests and upgrade only when the browser asked for one, which is the approach the Nginx documentation shows. The map block goes outside the server block, in the http context.
Disconnects after 60 seconds
If the WebSocket opens fine but drops after a minute with nothing being sent, that's not a bug. Nginx's documentation says the connection “will be closed if the proxied server does not transmit any data within 60 seconds.” In the lab, an idle WebSocket was closed after exactly 60 seconds with the default setting, and after 10 seconds with proxy_read_timeout 10s;.
Fix: the better fix is in the app: have it send WebSocket ping frames every 30 seconds or so, which the Nginx documentation also suggests. Most WebSocket libraries have a setting for this. If you can't change the app, raise the timeout for that location only:
location /ws/ {
# ... the lines above ...
proxy_read_timeout 1h;
}
Apache
Since Apache 2.4.47, the normal proxy module can carry WebSockets. Add upgrade=websocket to ProxyPass in the virtual host:
ProxyPass "/" "http://127.0.0.1:3000/" upgrade=websocket
Tested on Debian 12's Apache 2.4.71: without upgrade=websocket the handshake reached the app as a normal request and returned 200, so no WebSocket opened; with it, 101. Check your version with apachectl -v.
The older RewriteRule ^/?(.*) ws://127.0.0.1:3000/$1 [P,L] form also gave 101, and on 2.4.71 it worked even without mod_proxy_wstunnel enabled. Apache's documentation now marks mod_proxy_wstunnel as deprecated, because mod_proxy_http handles the upgrade. The rewrite form is still the only option in .htaccess, where ProxyPass isn't allowed (see ProxyPass not allowed in .htaccess); ProxyForge's .htaccess output uses it.
Apache waits much longer than Nginx before closing an idle connection: with Debian's default Timeout 300, an idle WebSocket was still open after 90 seconds in the lab.
Behind Cloudflare
Cloudflare's documentation says WebSockets are “supported on all Cloudflare plans” with no extra setup. It also says Cloudflare closes a WebSocket when no data is sent for a while, without giving a fixed number, and that restarting its servers “terminates WebSockets connections.” So behind Cloudflare, app-side pings matter even more, and your app should reconnect when a connection drops. (Not lab-tested: from Cloudflare's WebSockets documentation, checked 14 November 2026.)
Check it works
Send a WebSocket handshake with curl and read the first line of the reply:
curl -i -N --http1.1 --max-time 5 \
-H "Connection: Upgrade" -H "Upgrade: websocket" \
-H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
https://example.com/your-websocket-path
HTTP/1.1 101 Switching Protocols means the proxy is right. 426 or 505 means a line from the table above is missing. In the browser, open the developer tools, then the Network tab filtered to WS: a working socket shows status 101 and stays open.
Generate a reverse proxy config with WebSockets ticked →
How to use ProxyForge · FAQ: common errors · Guides · What's new · About