WebSocket failed 🟨 JavaScript

WebSocket connection to 'wss://x' failed

The browser couldn’t open (or keep) a WebSocket connection.

Seen on: JavaScript

Meaning

Proxies that don’t forward the Upgrade header, ws:// from an HTTPS page, wrong paths, and load balancer idle timeouts are typical.

Common causes

  • Reverse proxy not forwarding Upgrade/Connection headers
  • ws:// used on an HTTPS page (must be wss://)
  • Wrong URL/path or server down
  • Idle timeout closing the connection

⚡ Quick fix

  1. Configure proxy upgrade headers
  2. Use wss:// on HTTPS pages
  3. Send ping/heartbeats
  4. Check the server logs for the handshake

Detailed fix by platform

Nginx

  1. nginx
    proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

How to diagnose

  1. Handshake — Status of the upgrade request (101 expected)?
  2. Proxy — Upgrade headers forwarded?

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.