Lorsque Node-RED MQTT ne se connecte pas, le nœud reste généralement sur un anneau jaune « connecting » ou alterne entre connecté et déconnecté, et le reste de votre flow devient muet. Ce guide vous donne une méthode rapide et ordonnée pour trouver la cause : lire les bons logs, prouver que le broker est joignable en dehors de Node-RED, puis passer en revue ports, TLS, noms d'hôte, client IDs, identifiants et réseau des conteneurs jusqu'à ce que le statut passe au vert.
Reconnaître les symptômes
Le statut affiché sous un nœud mqtt in ou mqtt out est votre premier indice :
| Statut | Signification habituelle |
|---|---|
| Anneau jaune, « connecting » indéfiniment | Node-RED n'arrive pas du tout à établir la connexion : mauvais hôte ou port, incohérence TLS, pare-feu, DNS |
| Anneau rouge, « disconnected » | Le broker a refusé ou fermé la connexion ; vérifiez les identifiants et les logs |
| Vert puis rouge toutes les quelques secondes | Un autre client utilise le même client ID, ou problème de keepalive |
| Vert, mais aucun message | La connexion fonctionne ; le problème vient du topic, de la QoS ou de l'éditeur |
| Gris ou aucun statut | Le nœud n'est pas relié à une configuration de broker, ou le flow n'est pas déployé |
Retenez les deux derniers cas. Un statut vert signifie que la connexion fonctionne : passez directement aux topics. Beaucoup de signalements « ne se connecte pas » sont en réalité des problèmes d'abonnement.
Étape 1 : lire le log de Node-RED
L'éditeur n'affiche qu'un statut succinct. Le log de Node-RED contient la véritable erreur. Son emplacement dépend de la façon dont vous lancez Node-RED :
# Lancé depuis un terminal : le log est dans ce terminal
# Installé comme service systemd (p. ex. script Raspberry Pi)
journalctl -u nodered -f
# Docker
docker logs -f nodered
Cherchez les lignes du nœud broker MQTT telles que Connection failed to broker: .... Le texte après les deux-points, par exemple Connection refused: Not authorized, getaddrinfo ENOTFOUND, ECONNREFUSED ou une erreur de certificat, vous oriente directement vers l'une des sections ci-dessous.
Étape 2 : tester en dehors de Node-RED
Avant de modifier quoi que ce soit dans Node-RED, prouvez que la machine peut joindre le broker. Les clients Mosquitto sont le moyen le plus rapide. Essayez d'abord le serveur MQTT public gratuit, qui ne demande aucun identifiant et sert aux tests, pas aux données de production :
mosquitto_sub -h broker.connectmq.com -p 1883 -i nr-test-6b0e \
-t "connectmq/demo/6b0e/#" -v
Dans un second terminal :
mosquitto_pub -h broker.connectmq.com -p 1883 -i nr-test-pub-6b0e \
-t "connectmq/demo/6b0e/ping" -m "hello"
Si hello apparaît, le MQTT sortant fonctionne depuis cette machine. Testez maintenant votre broker privé exactement comme Node-RED s'y connectera, avec TLS et identifiants :
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
L'option -d affiche les paquets CONNECT et CONNACK. Si cette commande échoue, le problème vient du réseau, du certificat ou des identifiants, pas de Node-RED. Si elle réussit et que Node-RED échoue toujours, comparez les réglages de Node-RED champ par champ avec cette commande. Arrêtez le client de test avant de lancer Node-RED, car il utilise le même client ID.
Étape 3 : vérifier ensemble serveur, port et TLS
La plupart des boucles de connexion proviennent d'une incohérence entre le port et les réglages TLS. La plupart des brokers utilisent ces ports standard :
| Port | Transport | Réglages du nœud broker Node-RED |
|---|---|---|
| 1883 | MQTT sur TCP | Use TLS décoché |
| 8883 | MQTT sur TLS | Use TLS coché |
| 8083 | MQTT sur WebSocket | Serveur ws://host:8083/mqtt |
| 8084 | MQTT sur WebSocket sécurisé | Serveur wss://host:8084/mqtt |
Erreurs fréquentes :
- Port 8883 sans TLS. Node-RED envoie du MQTT en clair vers un port TLS ; le broker attend une négociation TLS et le nœud se reconnecte en boucle.
- Port 1883 avec TLS coché. Node-RED lance une négociation TLS sur un port en clair et échoue.
- Schéma dans le champ serveur. Saisissez uniquement le nom d'hôte, comme
broker.connectmq.com, pour TCP et TLS. N'utilisez une URLws://ouwss://que si vous comptez vous connecter via WebSocket. - Fautes de frappe et espaces. Un espace en fin de nom d'hôte produit des erreurs DNS difficiles à repérer.
Pour TLS, vérifiez aussi que Verify server certificate est activé et que le nom du serveur correspond au certificat. ConnectMQ utilise un certificat Let's Encrypt, auquel Node.js fait confiance par défaut : vous n'avez donc pas besoin d'importer de fichier CA. Si vous avez ajouté une configuration TLS personnalisée avec un ancien fichier CA, supprimez-la. La configuration complète figure dans Node-RED MQTT TLS.
Étape 4 : écarter les client IDs en double
Les brokers MQTT n'autorisent qu'une connexion par client ID. Lorsqu'un second client se connecte avec le même identifiant, le broker déconnecte le premier. Si les deux clients se reconnectent automatiquement, ils s'éjectent mutuellement sans fin, ce qui se traduit par un statut qui alterne entre connecté et déconnecté.
Sources typiques de doublons :
- Deux instances Node-RED, par exemple un ordinateur portable et un Raspberry Pi, déployées avec le même flow.
- Un
mosquitto_subde test resté actif avec le client ID de Node-RED. - Un conteneur Docker recréé alors que l'ancien tourne encore.
- Deux nœuds de configuration de broker dans un même Node-RED avec le même identifiant.
Donnez un identifiant unique à chaque instance. Sur le broker public, n'importe quelle chaîne unique non vide convient. Sur les brokers privés ConnectMQ, les client IDs sont liés aux identifiants délivrés : utilisez le client ID affiché dans le portail et ne réutilisez pas ce jeu d'identifiants sur une seconde instance ; créez plutôt un autre identifiant pour celle-ci.
Étape 5 : vérifier les identifiants et les limites du compte
Une connexion refusée juste après la connexion signale généralement un problème d'authentification. Avec MQTT 3.1.1, vous verrez les codes de retour 4 ou 5 (nom d'utilisateur ou mot de passe incorrect, non autorisé) ; avec MQTT 5, des reason codes comme 0x86 ou 0x87. Ressaisissez le nom d'utilisateur et le mot de passe dans l'onglet Security du nœud broker, puis déployez. Les identifiants sont stockés séparément des flows : importer un flow sur une nouvelle machine apporte les réglages du broker, mais pas le mot de passe.
Deux causes moins évidentes :
- Échecs de connexion répétés. ConnectMQ bloque une adresse IP après des tentatives de connexion échouées répétées. Si vous avez déployé un mauvais mot de passe et que Node-RED a réessayé de nombreuses fois, corrigez les identifiants et laissez le blocage se lever avant de conclure que le nouveau mot de passe est faux lui aussi.
- Quotas de connexions. Chaque offre a une limite de connexions ; l'offre gratuite Serverless autorise jusqu'à 25 connexions. Au-delà, un broker MQTT 5 peut refuser avec le reason code
0x97(quota exceeded). Comptez tous vos équipements, tableaux de bord et instances Node-RED.
Étape 6 : corriger le réseau, le DNS et les conteneurs
Si le log affiche ENOTFOUND, ETIMEDOUT ou ECONNREFUSED :
- Pare-feu. Les réseaux d'entreprise et certains réseaux invités bloquent les ports sortants 1883 et 8883. Essayez le WebSocket sécurisé sur le port 8084, qui passe souvent là où le MQTT brut est bloqué.
- localhost dans Docker. Dans un conteneur,
localhostdésigne le conteneur lui-même. Utilisez le nom d'hôte du broker, un nom de service Compose ouhost.docker.internal; voir Node-RED avec Docker. - DNS. Exécutez
nslookup YOUR_BROKER_HOSTsur l'hôte Node-RED. Les passerelles dont le DNS est mal configuré échouent d'abord ici. - Proxys. Le client MQTT de Node-RED ne passe pas par un proxy HTTP pour le TCP brut ; les connexions WebSocket s'accommodent souvent mieux des proxys.
Étape 7 : vérifier le keepalive et les réglages de session
Si la connexion tombe toutes les une ou deux minutes sur un réseau par ailleurs sain, regardez le keepalive. Une valeur de 60 secondes convient à la plupart des liaisons. Des valeurs très longues laissent les routeurs NAT supprimer silencieusement les connexions inactives. Vérifiez aussi que les réglages Clean session et la version du protocole correspondent à ce qu'attend votre flow. Utiliser des fonctionnalités MQTT 5 avec un nœud broker réglé en 3.1.1 n'empêche pas la connexion, mais peut expliquer des comportements étranges une fois connecté.
Check-list de dépannage rapide
- Le flow est-il déployé et le nœud MQTT relié à une configuration de broker ?
- Le log de Node-RED affiche-t-il une erreur précise ?
mosquitto_subse connecte-t-il depuis la même machine avec les mêmes réglages ?- Les réglages de port et de TLS concordent-ils (1883 en clair, 8883 en TLS) ?
- Le champ serveur contient-il un simple nom d'hôte, sans faute de frappe ?
- Le client ID est-il unique parmi tous les clients en cours d'exécution ?
- Le nom d'utilisateur et le mot de passe sont-ils corrects, et votre IP n'est-elle pas temporairement bloquée ?
- Êtes-vous sous la limite de connexions de votre offre ?
- Le DNS résout-il le nom et le port est-il ouvert depuis ce réseau ou ce conteneur ?
Si le statut est vert mais que les messages n'arrivent pas, vérifiez les topics et les wildcards, et consultez le tutoriel Node-RED MQTT pour un flow éprouvé. La documentation officielle des nœuds MQTT de Node-RED explique aussi chaque réglage du broker.
Choisissez un broker facile à déboguer
Le dépannage va plus vite lorsque vous voyez le côté broker. ConnectMQ est un broker MQTT managé dont le portail inclut un client MQTT dans le navigateur et un explorateur de topics en direct, pour vérifier si les messages de Node-RED arrivent. Vous pouvez aussi vous abonner à $SYS/broker/connection/{clientId}/state pour savoir si un client précis est connecté. Créez gratuitement un broker Serverless sur app.connectmq.com, sans carte bancaire, et copiez dans Node-RED l'hôte, le port, le nom d'utilisateur, le mot de passe et le client ID exacts. Pour aller plus loin, lisez comment choisir un broker MQTT cloud.
Questions fréquentes
Pourquoi mon nœud MQTT Node-RED reste-t-il bloqué sur connecting ?
Le plus souvent, l'hôte ou le port est incorrect, le TLS ne correspond pas au port, ou un pare-feu bloque la connexion. Consultez le log de Node-RED pour l'erreur exacte et testez les mêmes réglages avec mosquitto_sub.
Pourquoi mon nœud MQTT Node-RED se connecte-t-il et se déconnecte-t-il sans arrêt ?
La cause la plus fréquente est un client ID en double : un autre client avec le même identifiant reprend sans cesse la session. Donnez un client ID unique à chaque instance Node-RED et à chaque outil de test.
Dois-je importer un certificat CA pour me connecter à ConnectMQ ?
Non. ConnectMQ utilise un certificat Let's Encrypt auquel Node.js fait confiance par défaut. Cochez Use TLS, utilisez le port 8883 et laissez la vérification du certificat activée.
Node-RED peut-il se connecter à MQTT à travers un pare-feu d'entreprise ?
Si les ports 1883 et 8883 sont bloqués, essayez MQTT sur WebSocket sécurisé via le port 8084 avec le chemin /mqtt, qui a plus de chances d'être autorisé.
