Browser WebSocket Errors — Connection Failed, Closed & Protocol Errors

Fix WebSocket errors including 'WebSocket connection failed', error code 1006 (abnormal closure), 1008 (policy violation), and handshake upgrade failures. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: WebSocket provides full-duplex communication between browser and server over a single TCP connection. The connection starts as HTTP and upgrades to WebSocket via 101 Switching Protocols. Close code 1000: normal closure, 1001: going away, 1006: abnormal (no close frame), 1008: policy violation. WSS (WebSocket Secure) must be used on HTTPS pages — mixing WS on HTTPS is blocked as mixed content. Proxies and load balancers may not properly handle WebSocket upgrade requests. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: Server WebSocket endpoint not running or incorrect URL. Proxy or load balancer not configured to pass WebSocket upgrade headers. Mixed content: using ws:// on an https:// page (must use wss://). CORS-like restrictions blocking WebSocket connections to different origins. Server closing connection due to idle timeout (no heartbeat/ping). Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Check the WebSocket URL: use wss:// for HTTPS pages, ws:// for HTTP pages. Verify server endpoint is accessible: use a WebSocket test tool (websocket.org/echo.html). Configure proxy for WebSocket: Nginx needs proxy_http_version 1.1 and proxy_set_header Upgrade. Implement heartbeat/ping: send periodic pings to prevent idle timeout disconnections. Check DevTools > Network > WS tab for detailed WebSocket frame inspection. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our Browser Errors collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.