Cuando Node-RED MQTT no conecta, el nodo suele quedarse con un anillo amarillo de "connecting" o alterna entre connected y disconnected, y el resto de tu flujo se queda en silencio. Esta guía te ofrece una forma rápida y ordenada de encontrar la causa: leer los logs adecuados, demostrar que el broker es accesible fuera de Node-RED y después revisar puertos, TLS, nombres de host, client IDs, credenciales y red de contenedores hasta que el estado se ponga en verde.
Conoce los síntomas
El estado que aparece bajo un nodo mqtt in o mqtt out es tu primera pista:
| Estado | Lo que suele significar |
|---|---|
| Anillo amarillo, "connecting" indefinidamente | Node-RED no logra completar la conexión: host o puerto incorrectos, TLS que no coincide, firewall, DNS |
| Anillo rojo, "disconnected" | El broker rechazó o cerró la conexión; revisa las credenciales y los logs |
| Verde y luego rojo cada pocos segundos | Otro cliente usa el mismo client ID, o hay problemas de keepalive |
| Verde, pero sin mensajes | La conexión está bien; el problema es el topic, el QoS o el publicador |
| Gris o sin estado | El nodo no está vinculado a una configuración de broker o el flujo no está desplegado |
Fíjate en los dos últimos. Un estado verde significa que la conexión funciona, así que salta directamente a los topics. Muchos informes de "no conecta" son en realidad problemas de suscripción.
Paso 1: lee el log de Node-RED
El editor solo muestra un estado breve. El log de Node-RED contiene el error real. Dónde encontrarlo depende de cómo ejecutes Node-RED:
# Iniciado desde una terminal: el log está en esa terminal
# Instalado como servicio systemd (p. ej. con el script de Raspberry Pi)
journalctl -u nodered -f
# Docker
docker logs -f nodered
Busca líneas del nodo broker MQTT como Connection failed to broker: .... El texto tras los dos puntos, por ejemplo Connection refused: Not authorized, getaddrinfo ENOTFOUND, ECONNREFUSED o un error de certificado, te lleva directamente a una de las secciones siguientes.
Paso 2: prueba fuera de Node-RED
Antes de cambiar nada en Node-RED, demuestra que la máquina puede llegar al broker. Los clientes de Mosquitto son la forma más rápida. Prueba primero con el servidor MQTT público gratuito, ya que no necesita credenciales:
mosquitto_sub -h broker.connectmq.com -p 1883 -i nr-test-6b0e \
-t "connectmq/demo/6b0e/#" -v
En una segunda terminal:
mosquitto_pub -h broker.connectmq.com -p 1883 -i nr-test-pub-6b0e \
-t "connectmq/demo/6b0e/ping" -m "hello"
Si aparece hello, el MQTT saliente funciona desde esta máquina. Ahora prueba tu broker privado exactamente como se conectará Node-RED, con TLS y credenciales:
mosquitto_sub -h YOUR_BROKER_HOST -p 8883 \
--capath /etc/ssl/certs \
-u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID \
-t "test/#" -v -d
El parámetro -d muestra los paquetes CONNECT y CONNACK. Si este comando falla, el problema es la red, el certificado o las credenciales, no Node-RED. Si funciona y Node-RED sigue fallando, compara los ajustes de Node-RED campo por campo con este comando. Detén el cliente de prueba antes de iniciar Node-RED, porque usa el mismo client ID.
Paso 3: revisa a la vez servidor, puerto y TLS
La mayoría de los bucles de conexión se deben a una discrepancia entre el puerto y los ajustes TLS. La mayoría de los brokers usan estos puertos estándar:
| Puerto | Transporte | Ajustes del nodo broker de Node-RED |
|---|---|---|
| 1883 | MQTT sobre TCP | Use TLS desmarcado |
| 8883 | MQTT sobre TLS | Use TLS marcado |
| 8083 | MQTT sobre WebSocket | Server ws://host:8083/mqtt |
| 8084 | MQTT sobre WebSocket seguro | Server wss://host:8084/mqtt |
Errores habituales:
- Puerto 8883 sin TLS. Node-RED envía MQTT sin cifrar a un puerto TLS; el broker espera un handshake TLS y el nodo se reconecta sin parar.
- Puerto 1883 con TLS marcado. Node-RED inicia un handshake TLS contra un puerto sin cifrar y falla.
- Esquema en el campo del servidor. Escribe solo el nombre de host, como
broker.connectmq.com, para TCP y TLS. Usa una URLws://owss://solo cuando quieras conectarte por WebSocket. - Erratas y espacios. Un espacio al final del nombre de host provoca errores de DNS difíciles de detectar.
Para TLS, comprueba también que Verify server certificate está activado y que el nombre del servidor coincide con el certificado. ConnectMQ usa un certificado de Let's Encrypt, en el que Node.js confía por defecto, así que no necesitas subir un archivo de CA. Si añadiste una configuración TLS personalizada con un archivo de CA antiguo, elimínala. La configuración completa está en Node-RED MQTT TLS.
Paso 4: descarta client IDs duplicados
Los brokers MQTT solo permiten una conexión por client ID. Cuando un segundo cliente se conecta con el mismo ID, el broker desconecta al primero. Si ambos clientes se reconectan automáticamente, se expulsan mutuamente sin fin, lo que se ve como un estado que alterna entre connected y disconnected.
Orígenes típicos de duplicados:
- Dos instancias de Node-RED, como un portátil y una Raspberry Pi, desplegadas con el mismo flujo.
- Un
mosquitto_subde prueba que se quedó en marcha con el client ID de Node-RED. - Un contenedor Docker recreado mientras el antiguo sigue en ejecución.
- Dos nodos de configuración de broker en un mismo Node-RED con el mismo ID.
Da a cada instancia un ID único. En el broker público sirve cualquier cadena única no vacía. En los brokers privados de ConnectMQ, los client IDs están vinculados a las credenciales emitidas, así que usa el client ID que muestra el portal y no reutilices ese conjunto de credenciales en una segunda instancia; crea otra credencial para ella.
Paso 5: revisa las credenciales y los límites de la cuenta
Una conexión rechazada justo después de conectar suele indicar un problema de autenticación. Con MQTT 3.1.1 verás los códigos de retorno 4 o 5 (usuario o contraseña incorrectos, no autorizado); con MQTT 5 verás reason codes como 0x86 o 0x87. Vuelve a introducir el usuario y la contraseña en la pestaña Security del nodo broker y despliega. Las credenciales se guardan separadas de los flujos, así que al importar un flujo en una máquina nueva te llevas los ajustes del broker, pero no la contraseña.
Dos causas menos evidentes:
- Intentos de login fallidos repetidos. ConnectMQ bloquea una dirección IP tras varios intentos de login fallidos. Si desplegaste una contraseña incorrecta y Node-RED reintentó muchas veces, corrige las credenciales y espera a que se levante el bloqueo antes de concluir que la nueva contraseña también es incorrecta.
- Cuotas de conexión. Cada plan tiene un límite de conexiones; el plan Serverless gratuito permite hasta 25 conexiones. Por encima del límite, un broker MQTT 5 puede rechazar con el reason code
0x97(cuota superada). Cuenta todos tus dispositivos, paneles e instancias de Node-RED.
Paso 6: corrige la red, el DNS y los contenedores
Si el log muestra ENOTFOUND, ETIMEDOUT o ECONNREFUSED:
- Firewalls. Las redes corporativas y algunas redes de invitados bloquean el tráfico saliente a los puertos 1883 y 8883. Prueba WebSocket seguro en el 8084, que a menudo pasa donde el MQTT directo no lo hace.
- localhost en Docker. Dentro de un contenedor,
localhostes el propio contenedor. Usa el nombre de host del broker, un nombre de servicio de Compose ohost.docker.internal; consulta Node-RED en Docker. - DNS. Ejecuta
nslookup YOUR_BROKER_HOSTen el host de Node-RED. Los gateways con DNS mal configurado fallan aquí primero. - Proxies. El cliente MQTT de Node-RED no enruta TCP directo a través de un proxy HTTP; las conexiones WebSocket pueden llevarse mejor con los proxies.
Paso 7: revisa los ajustes de keepalive y de sesión
Si la conexión se cae cada uno o dos minutos en una red por lo demás sana, revisa el keepalive. Un valor de 60 segundos sirve para la mayoría de los enlaces. Los valores muy largos permiten que los routers NAT descarten en silencio las conexiones inactivas. Asegúrate también de que los ajustes de Clean session y la versión del protocolo coinciden con lo que espera tu flujo. Usar funciones de MQTT 5 en un nodo broker configurado en 3.1.1 no impedirá la conexión, pero puede explicar comportamientos extraños una vez conectado.
Lista rápida de solución de problemas
- ¿Está el flujo desplegado y el nodo MQTT vinculado a una configuración de broker?
- ¿Muestra el log de Node-RED un error concreto?
- ¿Se conecta
mosquitto_subdesde la misma máquina con los mismos ajustes? - ¿Coinciden los ajustes de puerto y TLS (1883 sin cifrar, 8883 con TLS)?
- ¿El campo del servidor es un nombre de host sin más y sin erratas?
- ¿Es el client ID único entre todos los clientes en ejecución?
- ¿Son correctos el usuario y la contraseña, y tu IP no está bloqueada temporalmente?
- ¿Estás por debajo del límite de conexiones de tu plan?
- ¿Resuelve el DNS y está abierto el puerto desde esta red o contenedor?
Si el estado está en verde pero no llegan mensajes, revisa los topics y los comodines, y consulta el tutorial de Node-RED MQTT para ver un flujo que funciona. La documentación oficial de los nodos MQTT de Node-RED también explica cada ajuste del broker.
Consigue un broker fácil de depurar
Solucionar problemas es más rápido cuando puedes ver el lado del broker. ConnectMQ es un broker MQTT gestionado con un portal que incluye un cliente MQTT en el navegador y un explorador de topics en directo, para que compruebes si llegan los mensajes de Node-RED. También puedes suscribirte a $SYS/broker/connection/{clientId}/state para ver si un cliente concreto está conectado. Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito, y copia exactamente el host, el puerto, el usuario, la contraseña y el client ID en Node-RED. Para más contexto, lee sobre cómo elegir un broker MQTT en la nube.
Preguntas frecuentes
¿Por qué mi nodo MQTT de Node-RED se queda en connecting?
Normalmente el host o el puerto son incorrectos, TLS no coincide con el puerto o un firewall bloquea la conexión. Revisa el log de Node-RED para ver el error exacto y prueba los mismos ajustes con mosquitto_sub.
¿Por qué mi nodo MQTT de Node-RED se conecta y se desconecta continuamente?
La causa más habitual es un client ID duplicado: otro cliente con el mismo ID se queda con la sesión una y otra vez. Da a cada instancia de Node-RED y a cada herramienta de prueba un client ID único.
¿Necesito subir un certificado de CA para conectarme a ConnectMQ?
No. ConnectMQ usa un certificado de Let's Encrypt en el que Node.js confía por defecto. Marca Use TLS, usa el puerto 8883 y deja activada la verificación del certificado.
¿Puede Node-RED conectarse a MQTT a través de un firewall corporativo?
Si los puertos 1883 y 8883 están bloqueados, prueba MQTT sobre WebSocket seguro en el puerto 8084 con la ruta /mqtt, que tiene más probabilidades de estar permitido.
