Errores de conexión MQTT: causas y soluciones

Una conexión MQTT puede fallar en cuatro capas: la red (DNS y TCP), el transporte (TLS o WebSocket), el handshake de MQTT (CONNECT / CONNACK) y la sesión activa (keep-alive y desconexiones). Identificar la capa es media solución. Esta guía las recorre una a una, con los mensajes de error y reason codes exactos que probablemente verás.

Diagnóstico rápido

Timeouts de conexión

Un timeout significa que tus paquetes salieron y no volvió nada. El broker ni siquiera tuvo la oportunidad de decir que no. Comprueba, en este orden:

1. Que el puerto corresponda al transporte. mqtt:// en 1883, mqtts:// en 8883, wss:// en el puerto WebSocket del broker. Consulta puertos MQTT explicados.
2. Que tu red permita el puerto. Las redes corporativas y de invitados suelen bloquear 1883 y 8883. Prueba wss:// en el 443 para confirmarlo.
3. Que el broker esté funcionando. Los sandboxes públicos se reinician sin previo aviso; prueba con otro broker para descartar tu propia configuración.
4. Que el firewall de tu servidor esté abierto. En brokers autoalojados, el security group del cloud debe permitir tráfico entrante en el puerto del listener.

ECONNREFUSED

ECONNREFUSED es un rechazo rápido y explícito del sistema operativo: el host es accesible, pero no hay ningún proceso escuchando en ese puerto. Las causas típicas son un broker que no está en marcha, un listener enlazado solo a 127.0.0.1, un puerto de contenedor que nunca se publicó (docker run -p 1883:1883) o conectarse a localhost desde dentro de un contenedor cuando el broker vive en otro.

Errores de TLS

• CA autofirmada o desconocida (SELF_SIGNED_CERT_IN_CHAIN, UNABLE_TO_VERIFY_LEAF_SIGNATURE): proporciona al cliente el archivo de la CA. No desactives la verificación fuera de las pruebas en local.
• El hostname no coincide (ERR_TLS_CERT_ALTNAME_INVALID): conéctate usando el nombre que figura en el certificado, no una dirección IP ni un alias interno.
• Wrong version number / packet length too long: estás hablando TLS con un puerto sin cifrar (por ejemplo, mqtts:// en 1883) o MQTT sin cifrar con un puerto TLS.
• Certificado caducado: comprueba las fechas con openssl s_client -connect host:8883 -servername host.

Errores exclusivos del navegador: contenido mixto y rutas WebSocket

Los navegadores solo pueden usar MQTT sobre WebSockets, y añaden sus propias reglas. Una página servida por HTTPS no puede abrir ws://: el navegador lo bloquea como contenido mixto antes de enviar ningún paquete, y el error solo aparece en la consola de desarrollo. Usa wss://. El otro error frecuente es olvidar la ruta: muchos brokers esperan /mqtt y, sin ella, el upgrade a WebSocket falla con un 404. Más información en MQTT sobre WebSockets.

Prueba una conexión wss que funciona

Códigos de retorno del CONNACK en MQTT 3.1.1

Si la red y el transporte funcionan, el broker responde al CONNECT con un CONNACK. En MQTT 3.1.1 lleva un código de retorno de un byte:

Reason codes habituales de MQTT 5

MQTT 5 sustituye los códigos de retorno por reason codes. Todo lo que sea 0x80 o superior es un fallo. Los mismos códigos pueden aparecer en el CONNACK o en un DISCONNECT enviado por el servidor:

Hay dos más que aparecen en paquetes DISCONNECT durante una sesión: 0x8D (Keep Alive timeout) y 0x8E (Session taken over). Ambos se explican más abajo. Para una visión general de lo que cambió en MQTT 5, consulta MQTT 5 vs 3.1.1.

Bucles por robo de client ID

La especificación obliga al broker a desconectar a un cliente existente cuando llega una nueva conexión con el mismo client ID. Si dos dispositivos —o dos pestañas del navegador— comparten ID y ambos se reconectan automáticamente, se van expulsando por turnos cada pocos segundos. En MQTT 5 el perdedor recibe un DISCONNECT con 0x8E; en 3.1.1 el socket simplemente se cierra.

Desconexiones por keep-alive

El valor de keep-alive del CONNECT indica al broker cada cuánto debe esperar tráfico. Si no ve nada durante una vez y media ese intervalo, cierra la conexión. Los clientes envían PINGREQ cuando están inactivos, pero un event loop bloqueado, un dispositivo dormido o un timeout de inactividad agresivo de un NAT o balanceador de carga pueden seguir rompiendo la conexión. Mantén el intervalo por debajo del timeout de inactividad de tu red (60 segundos es un valor por defecto habitual) y nunca bloquees el hilo que atiende al cliente MQTT.

Registra el error real

La mayoría de las librerías ocultan el motivo a menos que lo escuches explícitamente. Con MQTT.js:

import mqtt from 'mqtt';

const client = mqtt.connect('wss://broker.emqx.io:8084/mqtt', {
  protocolVersion: 5,
  clientId: `debug-${Math.random().toString(16).slice(2, 10)}`,
  reconnectPeriod: 5000,
});

client.on('connect', (connack) => console.log('connected', connack.reasonCode ?? 0));
client.on('error', (err) => console.error('error:', err.message, err.code));
client.on('disconnect', (packet) => console.warn('server disconnect, reason', packet.reasonCode));
client.on('close', () => console.warn('socket closed'));

Checklist

1. Confirma el circuito completo con un broker público que funcione en el cliente online.
2. Haz coincidir esquema, puerto y ruta con el listener documentado del broker.
3. Lee el código del CONNACK o el reason code en lugar de adivinar.
4. Usa un client ID único y reconecta con backoff.
5. Mantén el keep-alive por debajo de cualquier timeout de inactividad del camino.

Para un procedimiento de prueba completo, sigue cómo probar un broker MQTT.

Preguntas frecuentes