Codes de retour CONNACK MQTT 0 à 5 expliqués (MQTT 3.1.1)

Les codes de retour CONNACK MQTT sont les six valeurs, de 0 à 5, qu'un broker MQTT 3.1.1 renvoie pour indiquer à un client si sa connexion a été acceptée et, sinon, pourquoi. Ce guide explique chaque code, montre comment il apparaît dans les outils et bibliothèques courants, et vous donne une solution applicable en quelques minutes, avec des exemples sur le serveur MQTT public gratuit et sur un broker privé.

Ce que contient le paquet CONNACK

Après l'ouverture d'une connexion TCP par un client, son premier paquet doit être un CONNECT. Le broker répond par un CONNACK, un paquet fixe de quatre octets en MQTT 3.1.1 :

20 02 00 05
|  |  |  |
|  |  |  +-- Connect return code (ici 5 = Not authorized)
|  |  +----- Connect acknowledge flags (bit 0 = Session Present)
|  +-------- Remaining length (toujours 2)
+----------- Packet type 2 (CONNACK), flags 0

Le flag Session Present indique au client si le broker a repris une session stockée, ce qui compte pour les sessions persistantes. Le code de retour est le sujet de cet article. S'il est différent de 0, le broker ferme la connexion réseau juste après l'envoi du CONNACK, et le client doit corriger la cause avant de réessayer. Pour la disposition complète des octets de ce paquet et des autres, consultez le guide de la structure des paquets MQTT.

Les codes de retour CONNACK MQTT en un coup d'œil

Les valeurs 6 à 255 sont réservées en MQTT 3.1.1. Si votre bibliothèque en signale une, elle décode généralement par erreur un reason code MQTT 5, ce qui signifie que le client et le broker ne sont pas d'accord sur la version du protocole.

Comment chaque code de retour apparaît dans vos outils

Les messages d'erreur varient selon l'outil, ce qui rend leur recherche déroutante. Voici comment les mêmes codes apparaissent dans trois clients courants :

Paho fait correspondre en interne les codes 3.1.1 aux noms des reason codes MQTT 5 : vous pouvez donc voir la formulation MQTT 5 même sur une connexion 3.1.1. La référence des reason codes MQTT présente la correspondance complète.

Code 1 : Unacceptable Protocol Version

Le paquet CONNECT contient un octet de niveau de protocole : 4 pour MQTT 3.1.1, 5 pour MQTT 5.0 et 3 pour l'ancien MQTT 3.1. Si le broker ne prend pas en charge le niveau demandé, il répond avec le code 1.

Comment le corriger :

• Définissez explicitement la version du protocole au lieu de vous fier aux valeurs par défaut de la bibliothèque. Dans les outils Mosquitto, utilisez -V mqttv311 ou -V mqttv5 ; dans Paho, protocol=mqtt.MQTTv311 ; dans MQTT.js, protocolVersion: 4 ou 5.
• Évitez MQTT 3.1 (niveau 3). Les brokers MQTT managés modernes comme ConnectMQ prennent en charge 3.1.1 et 5.0.
• Si vous êtes derrière un proxy ou une passerelle, vérifiez qu'il laisse passer MQTT sans modification.

Code 2 : Identifier Rejected

Le broker n'a pas accepté l'identifiant client. Raisons courantes :

• Client ID vide avec clean session désactivé. MQTT 3.1.1 n'autorise un client ID de longueur nulle qu'avec clean session, et beaucoup de brokers rejettent purement et simplement les ID vides. Définissez toujours un ID non vide.
• Caractères ou longueur hors des règles du broker. Limitez-vous aux lettres, chiffres et tirets, et gardez des ID raisonnablement courts.
• Client ID lié aux identifiants. Certains brokers associent un client ID à un compte précis. Sur un broker ConnectMQ privé, les client ID sont liés aux identifiants émis dans le portail : utilisez donc le client ID qui y est affiché avec son nom d'utilisateur.

Sur le serveur MQTT public gratuit, tout ID non vide et unique fonctionne. Le guide du client ID MQTT présente des stratégies de nommage pour les flottes.

Code 3 : Server Unavailable

La connexion réseau a fonctionné, mais le broker ne peut pas servir MQTT pour le moment. C'est généralement passager : redémarrage, surcharge ou maintenance. Mettez en place un backoff exponentiel avec jitter plutôt que de vous reconnecter immédiatement ; des milliers d'appareils qui se reconnectent en même temps peuvent maintenir en surcharge un broker en cours de rétablissement.

Code 4 : Bad User Name or Password

Le broker a vérifié les identifiants et ils ne correspondent pas. En pratique :

• Recopiez le nom d'utilisateur et le mot de passe depuis la source de référence ; les espaces en fin de chaîne et les champs inversés sont fréquents.
• Vérifiez que votre bibliothèque envoie bien le mot de passe. Certaines API exigent username_pw_set() avant connect().
• Méfiez-vous des caractères spéciaux des mots de passe altérés par les guillemets du shell. Entourez-les d'apostrophes simples en ligne de commande.
• Ne bouclez pas sur les échecs. Les brokers se protègent couramment contre les attaques par force brute, et ConnectMQ bloque une adresse IP après des échecs de connexion répétés.

Code 5 : Not Authorized

Le broker a compris qui vous êtes mais refuse la connexion. Les causes incluent l'utilisation d'identifiants destinés à un autre broker, un client ID qui ne correspond pas, un compte désactivé ou un quota épuisé. C'est le refus le plus fréquent sur les brokers privés, et il dispose de sa propre check-list pas à pas dans corriger l'erreur MQTT connection refused: not authorized.

Reproduire les codes CONNACK en toute sécurité

Voir les codes par vous-même les rend plus faciles à reconnaître dans les journaux de production. D'abord, une connexion réussie au serveur MQTT public gratuit (réservé aux tests et aux prototypes, jamais aux données de production), avec la sortie de débogage activée :

mosquitto_sub -h broker.connectmq.com -p 1883 -i connack-test-4e8b \
  -t "connectmq/demo/4e8b/#" -V mqttv311 -d

Le flag -d affiche Client connack-test-4e8b received CONNACK (0), avec le code de retour entre parenthèses. Sur un broker privé, un mot de passe volontairement erroné montre le refus :

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u YOUR_USERNAME -P wrong-password -i YOUR_CLIENT_ID \
  -t "test/#" -V mqttv311 -d

Ne l'exécutez qu'une ou deux fois ; des échecs répétés peuvent déclencher un blocage de l'IP.

Gérer les codes de retour en Python

Ce client paho-mqtt 2.x se connecte en MQTT 3.1.1, journalise le code et s'arrête au lieu de réessayer sur les erreurs qui nécessitent une intervention humaine :

import paho.mqtt.client as mqtt

# Paho fait correspondre les codes 3.1.1 1, 2, 4, 5 aux valeurs MQTT 5 0x84, 0x85, 0x86, 0x87
FATAL = {0x84, 0x85, 0x86, 0x87}

def on_connect(client, userdata, flags, reason_code, properties):
    if not reason_code.is_failure:
        print("Connected, session present:", flags.session_present)
        client.subscribe("connectmq/demo/4e8b/#")
        return
    print(f"Connection refused: {reason_code}")
    if reason_code.value in FATAL:
        print("Configuration problem, not retrying")
        client.disconnect()
        client.loop_stop()

client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id="connack-py-4e8b",
    protocol=mqtt.MQTTv311,
)
client.on_connect = on_connect
client.connect("broker.connectmq.com", 1883, keepalive=60)
client.loop_forever()

Gérer les codes de retour en Node.js

MQTT.js émet un événement error avec une propriété code contenant la valeur numérique du CONNACK :

const mqtt = require("mqtt");

const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
  clientId: "YOUR_CLIENT_ID",
  username: "YOUR_USERNAME",
  password: "YOUR_PASSWORD",
  protocolVersion: 4,
  reconnectPeriod: 5000,
});

client.on("connect", () => console.log("CONNACK 0: connected"));

client.on("error", (err) => {
  console.error(`CONNACK ${err.code}: ${err.message}`);
  if ([1, 2, 4, 5].includes(err.code)) {
    client.end(true); // arrêter les reconnexions sur les erreurs de configuration
  }
});

Check-list rapide de dépannage CONNACK

1. Pouvez-vous seulement joindre l'hôte et le port ? Un timeout signifie qu'aucun CONNACK n'a jamais été envoyé ; vérifiez le DNS, le pare-feu et le port.
2. Utilisez-vous TLS sur 8883 et TCP simple sur 1883, et pas l'inverse ?
3. La version du protocole est-elle explicite et prise en charge ?
4. Le client ID est-il non vide, unique et bien celui émis avec vos identifiants ?
5. Le nom d'utilisateur et le mot de passe sont-ils exactement ceux qui ont été émis ?
6. Votre logique de reconnexion s'arrête-t-elle sur les codes 1, 2, 4 et 5 au lieu de marteler le broker ?

Des retours de connexion clairs avec ConnectMQ

ConnectMQ est un broker MQTT managé qui prend en charge MQTT 3.1.1 et 5.0 en TCP 1883, TLS 8883 et WebSockets. Le portail génère pour chaque broker un nom d'utilisateur, un mot de passe et un client ID qui vont ensemble, ce qui élimine la cause la plus fréquente des codes 2, 4 et 5. Créez un broker Serverless (Free) sur app.connectmq.com, sans carte bancaire. Vous découvrez les brokers ? Commencez par ce que fait un broker MQTT ou par le tutoriel MQTT complet.

Questions fréquentes

Que signifie le code de retour CONNACK 0 ?

Connexion acceptée. Le broker a accepté le CONNECT, et le flag Session Present du même paquet vous indique si une session précédente a été reprise.

Quelle est la différence entre les codes de retour 4 et 5 ?

Le code 4 signifie que le nom d'utilisateur ou le mot de passe ne correspond pas. Le code 5 signifie que le broker refuse le client pour une autre raison d'autorisation, comme un client ID non lié à ces identifiants ou un compte qui n'est pas autorisé à se connecter.

Pourquoi mon client ne reçoit-il aucun CONNACK ?

Si aucun CONNACK n'arrive, le problème se situe sous MQTT : mauvais hôte ou port, pare-feu, ou incompatibilité TLS comme du MQTT en clair envoyé sur le port 8883. Corrigez la connectivité avant de vous intéresser aux codes de retour.

MQTT 5 utilise-t-il les mêmes codes CONNACK ?

Non. MQTT 5 les remplace par des reason codes comme 0x86 et 0x87, qui apportent davantage de détails. Les six codes 3.1.1 ont des équivalents directs en MQTT 5.