Quick answer: Nginx doesn't pass the Upgrade and Connection headers to the backend unless you tell it to, so the WebSocket handshake fails (usually 400 Bad Request, or a 200 instead of 101 Switching Protocols). Add this to the location that serves your WebSocket path, and the map block to the http {} context:
map $http_upgrade $connection_upgrade { # in http {}
default upgrade;
'' close;
}
location /ws/ {
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 90s; # keep above your ping interval, see section 5
}
If connections open but drop after exactly 60 seconds, that's Nginx's default proxy_read_timeout: send a ping every 25 to 30 seconds and set the timeout above it.
Secure WebSockets (wss://) are not simply HTTPS requests with longer timeouts. A production WebSocket connection represents a stateful, bidirectional TCP tunnel that transitions from an HTTP/1.1 opening handshake into persistent framing.
Because Upgrade and Connection are HTTP hop-by-hop headers, standard reverse proxies strip them by default. Without explicit Nginx configuration, incoming WebSocket handshakes fail with 400 Bad Request or fall back to CPU-intensive HTTP long-polling.
# Verify Nginx configuration syntax and upstream connection support
sudo nginx -t
sudo nginx -T | grep -E "Upgrade|connection_upgrade|proxy_read_timeout"
Quick Triage: WebSocket Failure Modes and Fixes
| Symptom / Log Signature | Root Cause | Exact Nginx Directive / Action |
|---|---|---|
400 Bad Request on Handshake | Missing Upgrade/Connection headers or wrong upstream location | Add proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; |
Close Code 1006 Abnormal Closure | Idle TCP/TLS socket timeout, upstream crash, or edge RST | Enable application-level ping/pong heartbeats; align proxy_read_timeout above heartbeat interval |
| Drops Exactly at 60 Seconds | Nginx proxy_read_timeout defaults to 60s of upstream silence | Increase proxy_read_timeout 3600s; and implement 25s client-side keepalives |
TLS Handshake Failure on wss:// | Incomplete SSL certificate chain, SNI mismatch, or ALPN mismatch | Install full certificate bundle (fullchain.pem), verify TLS 1.2/1.3 with OpenSSL |
| Socket.IO Polling Fallback Loop | WebSocket upgrade blocked by proxy or CORS policy | Verify /socket.io/ location block explicitly passes upgrade headers and handles query parameters |
Session ID unknown / 400s Across Pods | Socket.IO HTTP polling distributed across multi-node cluster | Configure ip_hash; or cookie-based sticky sessions, backed by Redis Pub/Sub adapter |
Handshake Returns 200 OK (Not 101) | Request matched standard HTTP route instead of WebSocket block | Ensure location pattern isolates WebSocket traffic and forwards Upgrade: websocket |
Too many open files (EMFILE) | File Descriptor (FD) exhaustion under 50k+ connections | Raise worker_rlimit_nofile 200000; and systemd LimitNOFILE |
1. Protocol Architecture & The Hop-by-Hop Handshake
A secure WebSocket connection undergoes a strict multi-phase lifecycle before bi-directional message streaming begins:
Client (Browser / Native App)
│
▼ [ 1. TCP Handshake + TLS 1.3 Negotiation ]
┌────────────────────────────────────────────────────────┐
│ Edge Nginx (SSL Termination & Protocol Gateway) │
│ - Validates SNI, Terminates TLS │
│ - Inspects "Upgrade: websocket" & "Connection: Upgrade"│
│ - Evaluates map $http_upgrade $connection_upgrade │
└──────────────┬─────────────────────────────────────────┘
│
▼ [ 2. HTTP/1.1 Upgrade Request Forwarded ]
┌────────────────────────────────────────────────────────┐
│ Upstream Real-Time Backend Pool │
│ (Node.js Socket.IO / Go Gorilla / Python FastAPI) │
│ - Generates Sec-WebSocket-Accept │
│ - Emits "HTTP/1.1 101 Switching Protocols" │
└──────────────┬─────────────────────────────────────────┘
│
▼ [ 3. 101 Switching Protocols Response ]
┌────────────────────────────────────────────────────────┐
│ Bidirectional TCP Tunnel Established │
│ - Nginx ceases HTTP request parsing │
│ - Proxies raw WebSocket binary / text frames │
│ - Monitored by proxy_read_timeout and ping/pong │
└────────────────────────────────────────────────────────┘
Why Hop-by-Hop Headers Require Explicit Mapping
Per RFC 2616 and RFC 7230, HTTP hop-by-hop headers (Connection, Keep-Alive, Proxy-Authenticate, Upgrade) apply to a single transport link and must not be forwarded by proxies.
When Nginx proxies a request, it automatically converts hop-by-hop headers to Connection: close. To establish a WebSocket tunnel, Nginx must be explicitly instructed to reconstruct the hop-by-hop contract between itself and the upstream service.
2. The Canonical map $http_upgrade Directive
Place the map block inside the http {} context (typically /etc/nginx/nginx.conf):
# /etc/nginx/nginx.conf
http {
# Dynamically map the Connection header based on client Upgrade request
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
include /etc/nginx/conf.d/*.conf;
}
Why Naive Connection "upgrade" Breaks Standard HTTP
A common configuration mistake is hard-coding proxy_set_header Connection "upgrade"; globally or in a mixed API location:
# BROKEN ANTI-PATTERN: Forces Upgrade header on standard REST requests
location / {
proxy_pass http://backend;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade"; # Breaks ordinary HTTP/1.1 requests!
}
An ordinary request like GET /api/users has no Upgrade header, yet Nginx would still send Connection: upgrade to the backend. That's a request to switch protocols with no protocol named. Many backends ignore it, but it's wrong on every normal request, it can confuse proxies and some servers, and it stops Nginx from closing those connections cleanly.
The map block (the pattern from the Nginx documentation) avoids that:
- If the client sent an
Upgradeheader,$connection_upgradebecomesupgrade. - If it didn't,
$connection_upgradebecomesclose, the same as Nginx's normal behaviour for proxied requests.
3. Production-Hardened Nginx WSS Configuration
Below is the complete, production-ready virtual host configuration featuring TLS 1.3, dedicated real-time socket paths, connection pooling, and optimized buffer settings:
# /etc/nginx/conf.d/websocket.conf
upstream realtime_cluster {
# Load balance across application pods
least_conn;
server 10.0.10.11:3000 max_fails=3 fail_timeout=10s;
server 10.0.10.12:3000 max_fails=3 fail_timeout=10s;
server 10.0.10.13:3000 max_fails=3 fail_timeout=10s;
# Maintain idle keepalives for standard HTTP endpoints
keepalive 64;
}
# Redirect HTTP to Secure WebSockets / HTTPS
server {
listen 80;
listen [::]:80;
server_name ws.example.com;
return 301 https://$host$request_uri;
}
# WSS Edge Ingress
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name ws.example.com;
# SSL / TLS Hardening
ssl_certificate /etc/nginx/tls/fullchain.pem;
ssl_certificate_key /etc/nginx/tls/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL_WS:50m;
ssl_session_timeout 1d;
ssl_session_tickets off;
# Dedicated WebSocket Location Block
location /ws/ {
proxy_pass http://realtime_cluster;
# Mandatory WebSocket Protocol Upgrade Headers
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# Client Identity Preservation
proxy_set_header Host $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;
# Timeout & Keepalive Management
proxy_connect_timeout 10s;
proxy_send_timeout 3600s;
proxy_read_timeout 3600s;
# Disable buffering for real-time low-latency frame streaming
proxy_buffering off;
}
# Standard REST / Health Check Fallback
location / {
proxy_pass http://realtime_cluster;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $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;
}
}
Verify your SSL certificate deployment and TLS cipher suites with the Pingzo SSL Inspector.
4. Socket.IO & Multi-Node Cluster Considerations
Socket.IO is not raw WebSocket. By default, Socket.IO begins with HTTP long-polling before attempting an in-place protocol upgrade to WebSocket.
The Multi-Node Sticky Session Trap
In a multi-pod cluster, if an initial polling handshake creates a Session ID (sid) on Pod A, but the subsequent polling or upgrade request hits Pod B, Pod B rejects the request with 400 Bad Request: Session ID unknown.
Browser ──► Polling Request 1 (Creates SID=abc) ──► Pod A (State saved)
Browser ──► Polling Request 2 (Sends SID=abc) ──► Pod B (Unknown SID! -> 400 Error)
# PRODUCTION FIX: Enable IP-Hash or Sticky Session Routing for Socket.IO
upstream socketio_cluster {
ip_hash; # Routes the same client IP to the same pod
server 10.0.10.11:3000;
server 10.0.10.12:3000;
server 10.0.10.13:3000;
}
server {
listen 443 ssl;
server_name realtime.example.com;
location /socket.io/ {
proxy_pass http://socketio_cluster;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 90s;
proxy_send_timeout 90s;
proxy_buffering off;
}
}
[!IMPORTANT]
ip_hashsolves the HTTP polling handshake affinity, but it does not broadcast real-time messages across pods. You must combine Nginx sticky routing with a Redis Pub/Sub Adapter (@socket.io/redis-adapter) inside your Node.js application.
5. Connection Timeouts vs. Heartbeat Architecture
One of the most frequent support tickets in WebSocket infrastructure is: "Why do client connections terminate every 60 seconds?"
Why the 60-Second Drop Occurs
Nginx's proxy_read_timeout defaults to 60s. This setting measures the maximum allowable interval of silence between successive upstream read operations, not the total connection duration. If neither the client nor the server transmits a frame for 60 seconds, Nginx unilaterally closes the socket with TCP FIN.
The 24-Hour Timeout Anti-Pattern
Setting proxy_read_timeout 86400s; (24 hours) without application heartbeats is dangerous:
- When mobile clients switch cell towers, enter tunnels, or sleep, TCP sockets disconnect silently without sending
FIN/RSTpackets. - Without heartbeats, Nginx and upstream backends keep these zombie half-open sockets in memory for 24 hours.
- At scale, dead sockets exhaust file descriptors and kernel connection tables.
The Correct Production Heartbeat Pattern
Send application-level ping/pong frames every 25 to 30 seconds, and set proxy_read_timeout comfortably above the ping interval. A good rule: twice the ping interval plus 10 seconds, so one lost ping doesn't drop the connection.
// Node.js WebSocket (ws) Server Heartbeat Implementation
import { WebSocketServer } from 'ws';
const wss = new WebSocketServer({ port: 3000 });
function heartbeat() {
this.isAlive = true;
}
wss.on('connection', (ws) => {
ws.isAlive = true;
ws.on('pong', heartbeat);
});
// Ping clients every 25 seconds
const interval = setInterval(() => {
wss.clients.forEach((ws) => {
if (ws.isAlive === false) return ws.terminate(); // Terminate dead socket
ws.isAlive = false;
ws.ping();
});
}, 25000);
Set Nginx proxy_read_timeout 90s; to allow 2 missed pings before dropping the socket.
6. Linux Kernel & Socket Capacity for 100,000+ Concurrent WebSockets
Unlike short-lived REST queries, 100,000 active WebSockets require 100,000 client sockets plus 100,000 upstream sockets held in memory simultaneously.
File Descriptor Sizing (Two per Connection)
Every proxied WebSocket consumes two file descriptors on the Nginx host: one for the client side and one for the connection to the backend.
100,000 Concurrent WebSockets = 200,000 Open Sockets + System Overhead ≈ 250,000 FDs
Configure Nginx and systemd limits:
# /etc/nginx/nginx.conf
worker_processes auto;
worker_rlimit_nofile 500000;
events {
worker_connections 100000;
multi_accept on;
use epoll;
}
# /etc/systemd/system/nginx.service.d/override.conf
[Service]
LimitNOFILE=500000
Apply kernel socket buffer and backlog parameters:
# /etc/sysctl.d/99-websockets.conf
# System-wide file descriptor ceiling
fs.file-max = 2097152
# Socket listen backlog for connection bursts
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
# Ephemeral port range for upstream connections
net.ipv4.ip_local_port_range = 10240 65535
# TCP memory tuning for high concurrency
net.ipv4.tcp_rmem = 4096 87380 4194304
net.ipv4.tcp_wmem = 4096 65536 4194304
sudo sysctl --system
sudo systemctl daemon-reload
sudo systemctl restart nginx
7. Live CLI Diagnostics & Debugging Runbook
Step 1: Validate TLS Handshake and ALPN
openssl s_client -connect ws.example.com:443 -servername ws.example.com -alpn http/1.1
Look for Verify return code: 0 (ok) and ALPN protocol: http/1.1.
Step 2: Test WebSocket Opening Handshake with curl
curl -i -N --http1.1 \
-H "Connection: Upgrade" \
-H "Upgrade: websocket" \
-H "Sec-WebSocket-Version: 13" \
-H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
https://ws.example.com/ws/
--http1.1 matters: over HTTPS, curl otherwise negotiates HTTP/2, which has no Upgrade mechanism, and the test fails even when Nginx is configured correctly.
Expected response:
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Step 3: Interactive Testing with wscat
# Install wscat CLI
npm install -g wscat
# Connect and stream frames interactively
wscat -c wss://ws.example.com/ws/
Step 4: Monitor Real-Time Nginx Upgrade Logs
Configure a dedicated WebSocket log format:
log_format ws_log '$remote_addr [$time_local] "$request" '
'status=$status bytes=$body_bytes_sent '
'upstream=$upstream_addr up_status=$upstream_status '
'upgrade="$http_upgrade" conn="$http_connection" '
'req_time=$request_time';
access_log /var/log/nginx/ws_access.log ws_log;
tail -f /var/log/nginx/ws_access.log
Test status codes and header propagation using the Pingzo HTTP Status Code Checker and HTTP Header Checker.
8. Monitoring WebSocket Endpoints
A plain HTTP health check proves the web server answers. It doesn't prove the upgrade path works or that the real-time backend isn't stuck. Two things help:
- A health endpoint inside the WebSocket service (for example
GET /ws-health, routed through the same Nginx server block) that returns 200 only if the process can do its job: event loop responsive, Redis adapter connected. An HTTP monitor on that URL catches a dead backend or a broken proxy route. - Metrics from the WebSocket server itself: count abnormal closures (
1006) and how long pings take to come back, and alert when either jumps.
Pingzo covers the first part: HTTP checks every 1 to 15 minutes depending on your plan, an incident when 3 of the last 5 checks fail, and alerts to WhatsApp, Slack, Telegram, Discord or email. It checks HTTP responses and doesn't open WebSocket connections, so pair it with the server metrics above. To check your certificate chain for wss://, use the free SSL inspector.
Frequently Asked Questions
Why do WebSockets drop precisely after 60 seconds?
Nginx defaults proxy_read_timeout to 60s. If your upstream application does not transmit data or WebSocket ping frames within 60 seconds of silence, Nginx terminates the connection. Either increase proxy_read_timeout or implement 25-second application-level ping/pong heartbeats.
Can I proxy WebSockets over HTTP/2 in Nginx?
Classic WebSockets use the HTTP/1.1 Upgrade: websocket mechanism. RFC 8441 defines WebSockets over HTTP/2 using the Extended CONNECT method (:protocol = websocket), which requires specific upstream server support. For standard open-source Nginx reverse proxying, configure your WebSocket virtual host to negotiate HTTP/1.1 over TLS.
Does Cloudflare require special configuration for WebSockets?
Cloudflare supports WebSockets out-of-the-box on all plan tiers. Ensure the WebSockets toggle is enabled under Network settings in your Cloudflare dashboard. Note that Cloudflare imposes an idle client timeout of 100 seconds, making regular 25-second ping/pong heartbeats essential.
What causes WebSocket Error 1006?
Close code 1006 is a reserved client-side code indicating an abnormal closure where the TCP connection dropped without receiving a clean WebSocket closing handshake frame. Common culprits include intermediate firewall timeouts, Nginx proxy_read_timeout expiration, or upstream backend OOM crashes.
Related guides
- Nginx "upstream prematurely closed connection": How to Fix
- Fix: nginx bind() to 0.0.0.0:80 failed (98: Address already in use)
- Nginx "host not found in upstream" in Docker
- SSL "key values mismatch": certificate and private key don't match
Stop Finding Out About Outages from Angry Users
Get instant WhatsApp & Discord alerts the second your API, website, or server goes down. Setup in 30 seconds, with checks as often as every minute.