MQTT-CONNACK-Rückgabecodes 0 bis 5 erklärt (MQTT 3.1.1)

MQTT CONNACK Return Codes sind die sechs Werte von 0 bis 5, mit denen ein MQTT-3.1.1-Broker einem Client mitteilt, ob seine Verbindung angenommen wurde und, falls nicht, warum. Dieser Leitfaden erklärt jeden Code, zeigt, wie er in gängigen Tools und Bibliotheken erscheint, und liefert Ihnen eine Lösung, die Sie in wenigen Minuten umsetzen können, mit Beispielen gegen den öffentlichen MQTT-Broker und einen privaten Broker. Gerade in Industrie-4.0-Projekten, in denen Gateways an SPS und Maschinen unbeaufsichtigt laufen, entscheidet die richtige Reaktion auf jeden Code darüber, ob sich ein Gerät selbst erholt oder ein Techniker in die Halle muss.

Was das CONNACK-Paket enthält

Nachdem ein Client eine TCP-Verbindung geöffnet hat, muss sein erstes Paket CONNECT sein. Der Broker antwortet mit CONNACK, in MQTT 3.1.1 einem festen Paket von vier Byte:

20 02 00 05
|  |  |  |
|  |  |  +-- Connect Return Code (hier 5 = Not authorized)
|  |  +----- Connect Acknowledge Flags (Bit 0 = Session Present)
|  +-------- Remaining Length (immer 2)
+----------- Pakettyp 2 (CONNACK), Flags 0

Das Flag Session Present teilt dem Client mit, ob der Broker eine gespeicherte Session fortgesetzt hat, was für persistente Sessions wichtig ist. Um den Rückgabecode geht es in diesem Artikel. Ist er ungleich 0, schließt der Broker die Netzwerkverbindung direkt nach dem Senden des CONNACK, und der Client muss die Ursache beheben, bevor er es erneut versucht. Den vollständigen Byte-Aufbau dieses und anderer Pakete finden Sie im Leitfaden zur MQTT-Paketstruktur.

MQTT CONNACK Return Codes im Überblick

Die Werte 6 bis 255 sind in MQTT 3.1.1 reserviert. Meldet Ihre Bibliothek einen davon, dekodiert sie meist versehentlich einen MQTT-5-Reason-Code. Client und Broker sind sich dann über die Protokollversion uneinig.

Wie jeder Rückgabecode in Ihren Tools erscheint

Die Fehlermeldungen unterscheiden sich je nach Tool, was die Suche danach verwirrend macht. So sehen dieselben Codes in drei gängigen Clients aus:

Paho bildet die 3.1.1-Codes intern auf die Namen der MQTT-5-Reason-Codes ab, sodass Sie selbst bei einer 3.1.1-Verbindung die MQTT-5-Formulierung sehen können. Die Referenz der MQTT Reason Codes zeigt die vollständige Zuordnung.

Code 1: Unacceptable Protocol Version

Das CONNECT-Paket enthält ein Byte für das Protokoll-Level: 4 für MQTT 3.1.1, 5 für MQTT 5.0 und 3 für das alte MQTT 3.1. Unterstützt der Broker das angeforderte Level nicht, antwortet er mit Code 1.

So beheben Sie das:

• Setzen Sie die Protokollversion explizit, statt sich auf Bibliotheksstandards zu verlassen. In den Mosquitto-Tools nutzen Sie -V mqttv311 oder -V mqttv5, in Paho protocol=mqtt.MQTTv311, in MQTT.js protocolVersion: 4 oder 5.
• Vermeiden Sie MQTT 3.1 (Level 3). Ein moderner verwalteter MQTT-Broker wie ConnectMQ unterstützt 3.1.1 und 5.0.
• Wenn Sie hinter einem Proxy oder Gateway sitzen, prüfen Sie, ob er MQTT unverändert durchleitet.

Code 2: Identifier Rejected

Der Broker hat die Client-Kennung nicht akzeptiert. Häufige Gründe:

• Leere Client ID bei deaktivierter Clean Session. MQTT 3.1.1 erlaubt eine Client ID der Länge null nur zusammen mit Clean Session, und viele Broker lehnen leere IDs grundsätzlich ab. Setzen Sie immer eine nicht leere ID.
• Zeichen oder Länge außerhalb der Broker-Regeln. Bleiben Sie bei Buchstaben, Ziffern und Bindestrichen und halten Sie IDs angemessen kurz.
• Client ID an Zugangsdaten gebunden. Manche Broker binden eine Client ID an ein bestimmtes Konto. Auf einem privaten ConnectMQ-Broker sind Client IDs an die im Portal ausgegebenen Zugangsdaten gebunden. Verwenden Sie also die dort angezeigte Client ID zusammen mit dem zugehörigen Benutzernamen.

Auf dem öffentlichen MQTT-Broker funktioniert jede nicht leere, eindeutige ID. Der Leitfaden zur MQTT Client ID behandelt Namensstrategien für Flotten.

Code 3: Server Unavailable

Die Netzwerkverbindung hat funktioniert, aber der Broker kann MQTT gerade nicht bedienen. Das ist meist vorübergehend: ein Neustart, Überlast oder Wartung. Implementieren Sie exponentiellen Backoff mit Jitter, statt sofort neu zu verbinden; Tausende Geräte, die sich im Gleichschritt neu verbinden, etwa nach einem Netzausfall im ganzen Werk, können einen sich erholenden Broker in der Überlast halten.

Code 4: Bad User Name or Password

Der Broker hat die Zugangsdaten geprüft, und sie stimmten nicht. In der Praxis:

• Kopieren Sie Benutzername und Passwort erneut aus der maßgeblichen Quelle; abschließende Leerzeichen und vertauschte Felder sind häufig.
• Prüfen Sie, ob Ihre Bibliothek das Passwort tatsächlich sendet. Manche APIs verlangen username_pw_set() vor connect().
• Achten Sie darauf, dass Sonderzeichen in Passwörtern nicht durch das Quoting der Shell verändert werden. Setzen Sie sie auf der Kommandozeile in einfache Anführungszeichen.
• Wiederholen Sie Fehlversuche nicht in einer Schleife. Broker schützen sich häufig gegen Brute-Force-Versuche, und ConnectMQ sperrt eine IP-Adresse nach wiederholt fehlgeschlagenen Anmeldungen.

Code 5: Not Authorized

Der Broker weiß, wer Sie sind, lehnt die Verbindung aber ab. Ursachen sind etwa Zugangsdaten für einen anderen Broker, eine nicht passende Client ID, ein deaktiviertes Konto oder ein ausgeschöpftes Kontingent. Das ist die häufigste Ablehnung auf privaten Brokern, und sie hat ihre eigene Schritt-für-Schritt-Checkliste unter MQTT connection refused: not authorized beheben.

CONNACK-Codes gefahrlos reproduzieren

Wenn Sie die Codes selbst sehen, erkennen Sie sie in Produktionslogs leichter wieder. Zuerst eine erfolgreiche Verbindung zum öffentlichen MQTT-Broker mit aktivierter Debug-Ausgabe:

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

Das Flag -d gibt Client connack-test-4e8b received CONNACK (0) aus, mit dem Rückgabecode in Klammern. Gegen einen privaten Broker zeigt ein absichtlich falsches Passwort die Ablehnung:

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

Führen Sie das nur ein- oder zweimal aus; wiederholte Fehlversuche können eine IP-Sperre auslösen.

Rückgabecodes in Python behandeln

Dieser paho-mqtt-2.x-Client verbindet sich per MQTT 3.1.1, protokolliert den Code und hört bei Fehlern, die menschliches Eingreifen erfordern, auf, statt es erneut zu versuchen:

import paho.mqtt.client as mqtt

# Paho bildet die 3.1.1-Codes 1, 2, 4, 5 auf die MQTT-5-Werte 0x84, 0x85, 0x86, 0x87 ab
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()

Rückgabecodes in Node.js behandeln

MQTT.js löst ein error-Event mit einer Property code aus, die den numerischen CONNACK-Wert enthält:

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); // bei Konfigurationsfehlern nicht weiter neu verbinden
  }
});

Kurze Checkliste zur CONNACK-Fehlerbehebung

1. Erreichen Sie Host und Port überhaupt? Ein Timeout bedeutet, dass nie ein CONNACK gesendet wurde; prüfen Sie DNS, Firewall und Port.
2. Verwenden Sie TLS auf 8883 und reines TCP auf 1883, nicht umgekehrt?
3. Ist die Protokollversion explizit gesetzt und unterstützt?
4. Ist die Client ID nicht leer, eindeutig und diejenige, die mit Ihren Zugangsdaten ausgegeben wurde?
5. Stimmen Benutzername und Passwort exakt mit den ausgegebenen überein?
6. Stoppt Ihre Reconnect-Logik bei den Codes 1, 2, 4 und 5, statt den Broker zu bombardieren?

Klares Verbindungs-Feedback mit ConnectMQ

ConnectMQ ist ein verwalteter MQTT-Broker, der MQTT 3.1.1 und 5.0 über TCP 1883, TLS 8883 und WebSockets unterstützt. Das Portal erzeugt für jeden Broker passende Kombinationen aus Benutzername, Passwort und Client ID und beseitigt damit die häufigste Ursache der Codes 2, 4 und 5. Erstellen Sie unter app.connectmq.com einen kostenlosen Serverless-Broker, ganz ohne Kreditkarte. Neu bei Brokern? Beginnen Sie mit was ein MQTT-Broker macht oder dem vollständigen MQTT-Tutorial.

Häufig gestellte Fragen

Was bedeutet CONNACK-Rückgabecode 0?

Connection accepted. Der Broker hat das CONNECT angenommen, und das Flag Session Present im selben Paket zeigt Ihnen, ob eine frühere Session fortgesetzt wurde.

Was ist der Unterschied zwischen den Rückgabecodes 4 und 5?

Code 4 bedeutet, dass Benutzername oder Passwort nicht stimmten. Code 5 bedeutet, dass der Broker den Client aus einem anderen Autorisierungsgrund ablehnt, etwa weil die Client ID nicht an diese Zugangsdaten gebunden ist oder das Konto keine Verbindung herstellen darf.

Warum erhält mein Client überhaupt kein CONNACK?

Kommt kein CONNACK an, liegt das Problem unterhalb von MQTT: falscher Host oder Port, eine Firewall oder eine TLS-Unstimmigkeit, etwa reines MQTT an Port 8883. Beheben Sie zuerst die Konnektivität, bevor Sie sich Rückgabecodes ansehen.

Verwendet MQTT 5 dieselben CONNACK-Codes?

Nein. MQTT 5 ersetzt sie durch Reason Codes wie 0x86 und 0x87, die mehr Details liefern. Die sechs 3.1.1-Codes lassen sich direkt auf ihre MQTT-5-Entsprechungen abbilden.