WebSocket connection to '…' failed

The browser tried to open a WebSocket and the HTTP Upgrade never completed. Your live UI, chat, or signalling channel never connects.

What you see

WebSocket connection to 'wss://example.com/socket' failed:
Error during WebSocket handshake: Unexpected response code: 400
// or: failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED
// or: failed: Mixed Content: The page was loaded over HTTPS…

Firefox often says Firefox can't establish a connection to the server at wss://…. Socket.IO wraps the same failure as websocket error / transport fallback to long-polling.

Checklist

1. Scheme and mixed content — pages on https:// must use wss://. ws:// is blocked as mixed content. Local http:// pages may use ws:// to localhost.
2. Reverse proxy forgot Upgrade — nginx needs:

   proxy_http_version 1.1;
   proxy_set_header Upgrade $http_upgrade;
   proxy_set_header Connection "upgrade";
   proxy_set_header Host $host;
   proxy_read_timeout 60s;   # or higher for idle sockets

   Apache: RewriteEngine + Upgrade / Connection pass-through; Caddy usually handles it; Cloudflare WebSockets must be enabled on the zone.
3. Wrong path or 404/502 on handshake — hit the same URL with curl and look at the status before Upgrade. A 502 from an upstream that is down looks like “connection failed” in the browser. See 502 Bad Gateway.
4. TLS / certificate — wss:// fails on expired or name-mismatch certs the same way HTTPS does. Related: certificate has expired, ERR_CERT_COMMON_NAME_INVALID, SSL wrong version number (plain HTTP on a TLS port).
5. Auth cookies / CSRF on the handshake — first request is still HTTP. SameSite cookies, missing credentials, or a WAF challenge can return 401/403 and abort Upgrade. CORS does not apply the same way as XHR, but cookie rules do.
6. Load balancer without stickiness — Upgrade hits node A; later frames hit node B with no shared state. Enable sticky sessions or shared pub/sub for multi-node apps.
7. Idle timeouts — proxies kill quiet sockets; clients should ping or send heartbeats. Sudden close after ~60s is often the proxy, not your app logic.

Quick proof

# Should return 101 Switching Protocols (with a real key)
curl -i -N \
  -H 'Connection: Upgrade' \
  -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' \
  -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
  https://example.com/socket

If curl gets 200 HTML or 404, the proxy is not forwarding WebSockets. If curl gets 101 but the browser fails, check mixed content, extensions (ERR_BLOCKED_BY_CLIENT), or a service worker.

WebSocket vs WebRTC

Video-call apps often use a WebSocket for signalling and WebRTC for media. Fix the socket first, then ICE. Blurry video after connect is bandwidth/compression — Wirebook compression lesson.

Related

WebRTC ICE failed · NotAllowedError getUserMedia · Failed to fetch · 502 Bad Gateway · Mixed Content blocked · localhost refused to connect

Questions

Published 6 November 2026.