◆Error Codes Wiki

Browser WebSocket Errors — Connection Failed, Closed & Protocol Errors

Warningweb development

Overview

Fix WebSocket errors including 'WebSocket connection failed', error code 1006 (abnormal closure), 1008 (policy violation), and handshake upgrade failures.

Key Details

  • 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

Common Causes

  • 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)

Steps

  1. 1Check the WebSocket URL: use wss:// for HTTPS pages, ws:// for HTTP pages
  2. 2Verify server endpoint is accessible: use a WebSocket test tool (websocket.org/echo.html)
  3. 3Configure proxy for WebSocket: Nginx needs proxy_http_version 1.1 and proxy_set_header Upgrade
  4. 4Implement heartbeat/ping: send periodic pings to prevent idle timeout disconnections
  5. 5Check DevTools > Network > WS tab for detailed WebSocket frame inspection

Tags

browserwebsocketconnection1006real-time

More in Web Development

browser-cors-error-explainedBrowser CORS Error Explained — Cross-Origin Request Blocked
Warning
browser-indexeddb-errorsBrowser IndexedDB Errors — Quota Exceeded, Blocked & Corruption
Warning
browser-localstorage-quota-exceededBrowser localStorage Quota Exceeded — Storage Limit & Alternatives
Warning
browser-service-worker-errorsBrowser Service Worker Errors — Registration, Cache & Update Failures
Warning
browser-webgl-context-lostBrowser WebGL Context Lost — GPU Rendering Failure in Browser
Warning
browser-javascript-heap-out-of-memoryBrowser JavaScript Heap Out of Memory — Page Crash & Performance
Error

Frequently Asked Questions

Code 1006 means the connection was closed abnormally without a proper close handshake. Usually a network interruption, server crash, or proxy timeout.