Fallo de conexión WebSocket: cómo probarlo y qué significa el error 1006

Cuando un navegador dice que ha fallado una conexión WebSocket, la causa es casi siempre una de pocas: un proxy que no deja pasar WebSockets, un handshake que el servidor rechazó, un problema de certificado o una conexión cortada por parecer inactiva. Para saber cuál es, conéctate a la misma dirección con nuestro test de WebSocket, lee el código de cierre y revisa después el handshake.
Este artículo repasa esos pasos y la solución para cada causa.
Por qué el navegador te cuenta tan poco
Tu código recibe un evento error sin detalles, seguido de un cierre con el código 1006. Ese código no lo envía nunca un servidor. RFC 6455 lo reserva para que un extremo informe de una conexión que terminó sin mensaje de cierre, así que solo dice que algo salió mal.
La vaguedad es a propósito. Si una página pudiera distinguir un handshake rechazado de un puerto cerrado, un script podría usarlo para explorar la red del visitante. Por eso se ocultan los detalles a tu código y tienes que buscarlos en otro sitio:
- Las herramientas de desarrollo del navegador. En el panel Red (Network), filtra por WS y selecciona la conexión. Muestra el estado del handshake y todos los mensajes.
- La consola. El navegador registra ahí un motivo que tu código no puede leer.
- Los registros del servidor y del proxy, que ven lo que el navegador esconde.
Paso 1: prueba la dirección
Abre el test de WebSocket, escribe la dirección wss:// y conéctate. Registra cuánto tardó la conexión, cada mensaje en ambos sentidos y el código de cierre con su significado.
Si conecta aquí y no en tu app, compara las dos. Esta prueba tiene su propio origen y ninguno de los tokens de tu app, así que la diferencia suele estar en la autenticación o en una comprobación del origen. Si aquí también falla, prueba desde otra red, como el punto de acceso de un teléfono, para descartar una VPN o un proxy de empresa.
Paso 2: revisa el handshake
Un WebSocket empieza como una petición HTTP, y curl te muestra la respuesta que el navegador esconde:
curl -i -N --http1.1 \
-H "Connection: Upgrade" \
-H "Upgrade: websocket" \
-H "Sec-WebSocket-Version: 13" \
-H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
https://example.com/socketAñade -H "Origin: https://your-site.example" si tu servidor comprueba de dónde viene una conexión. La primera línea de la respuesta lo dice casi todo:
101 Switching Protocols. El handshake funciona, así que mira lo que pasa después.200. La petición llegó a una página normal, así que el proxy no la pasa como WebSocket, o la ruta es incorrecta.400. El servidor no aceptó el handshake. Algunos servidores también esperan de una petición más de lo que lleva esta.401o403. Falló la autenticación, o el origen no está permitido.404. No hay nada escuchando en esa ruta.502,503o504. El proxy no puede llegar al servidor que tiene detrás.
Si curl informa de un error de certificado, has encontrado la causa: un navegador rechaza la conexión de la misma manera y enseña a tu código el mismo 1006.
Las causas habituales y sus soluciones
El proxy no deja pasar WebSockets. Es la más común. Un proxy tiene que reenviar a propósito las cabeceras de actualización, y en nginx se hace así:
location /socket {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
}Se corta al cabo de un minuto más o menos. Los proxies y los balanceadores de carga cierran las conexiones que parecen inactivas, y el proxy_read_timeout de nginx es de 60 segundos si no lo cambias. Subirlo ayuda, pero envía un mensaje pequeño o un ping con más frecuencia que el tiempo de espera más corto del camino, ya que no controlas todos los proxies entre tú y tus usuarios.
ws:// desde una página HTTPS. Los navegadores lo bloquean como contenido mixto, salvo ws:// hacia localhost. Usa wss:// en una página servida por HTTPS.
Se rechaza el origen. Los servidores suelen permitir conexiones solo desde sus propios sitios y rechazan el resto durante el handshake. Añade la dirección de tu sitio a la lista.
No hay forma de enviar cabeceras. Ningún navegador puede poner cabeceras en un WebSocket, así que un token en una cabecera Authorization nunca llega. Envíalo en la cadena de consulta, como subprotocolo o en tu primer mensaje.
Falla en cada despliegue. Un reinicio corta todas las conexiones. Reconecta con una espera creciente y aleatoria para que no vuelvan todas a la vez, y no des por hecho que no se perdió nada mientras estabas fuera.
Qué dicen los códigos de cierre
Cuando una conexión ya se ha abierto, el código con el que se cierra merece una lectura:
- 1000: un cierre normal, a propósito.
- 1001: se va, como un servidor que se apaga o una página que se abandona.
- 1006: sin mensaje de cierre, como se explicó antes.
- 1008: el servidor la rechazó según sus normas, a menudo por la autenticación o el origen.
- 1011: algo salió mal en el servidor.
- 1012 y 1013: un reinicio, o inténtalo más tarde.
El test de WebSocket los lista todos con lo que significan. Los códigos a partir de 4000 pertenecen al servidor o a su biblioteca.
Si prefieres no mantener el servidor
Casi todo esto viene de mantener websockets por tu cuenta: el proxy, los tiempos de espera, los reinicios. Websockets en Python y en Laravel repasan lo que hace falta en cada framework, y por qué los alojamientos de WordPress no pueden mantener un websocket trata el alojamiento compartido.
Con WordPlus Cloud, tu app se conecta a nuestros servidores en tiempo real mediante nuestros SDK, con salas, presencia y reconexiones, y no mantienes ningún servidor WebSocket. Se factura por conexiones, a partir de 1.000, y la documentación tiene una guía para cada stack. Si falla una conexión con ella, el test de conexión muestra si esa red llega a nuestros servidores.