> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md).
# Dépannage
Dépannez les intégrations MQTT par phase d’échec — connexion au broker, TLS, authentification, routage des topics, dernière donnée.
Recettes de diagnostic pour les intégrations MQTT sur le serveur Kilo IoT, organisées selon l’endroit où l’échec se manifeste. Parcourez-les dans l’ordre — la plupart des problèmes se rangent dans l’une des trois premières phases, et la séquence de diagnostic permet de cerner efficacement la cause racine.
Avant de parcourir les phases ci-dessous, laissez la plateforme vous indiquer dans laquelle vous vous trouvez. Un seul appareil silencieux signale son propre état dans son **Connexion** onglet — à savoir si le broker est joignable, si une publication est arrivée sur un topic inattendu et si ses valeurs ont été enregistrées ; voir [Diagnostics de l’appareil](/kilo-docs-fr/kilo-iot-server/devices/device-diagnostics.md). Lorsque plusieurs appareils se taisent d’un coup, ouvrez la **diagnostics du connecteur** zone — **État de la source** résume l’abonnement au broker, **Entrant** montre ce qui arrive, et **Activité** montre l’historique récent des événements du connecteur. Cette lecture indique généralement directement la phase à partir de laquelle commencer.
## Phase 1 — Échecs de connexion au broker
**Symptôme :** l’émetteur (une passerelle de périphérie, une instance Zigbee2MQTT, un firmware personnalisé) indique qu’il ne peut pas se connecter au broker. **Dernières données reçues** ne se met jamais à jour.
| Schéma d’échec | Cause racine | Résolution |
| ------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connexion refusée` / `réseau injoignable` (MQTT Cloud) | Hôte, port ou schéma incorrects | Vérifiez que l’émetteur utilise `mqtts://` sur le port 1884 — et non le 1883 par défaut. Recopiez l’URL du broker depuis la page du connecteur. |
| `connexion refusée` / `réseau injoignable` (MQTT externe) | Joignabilité réseau | La plateforme se connecte à votre broker. Vérifiez que le broker est joignable depuis Internet public (le nom d’hôte DDNS résout, le transfert de port est actif, le pare-feu autorise la plage de sortie de la plateforme). |
| `échec de poignée de main TLS` / `la vérification du certificat a échoué` | Configuration TLS | Pour Cloud MQTT, le certificat est approuvé publiquement — vérifiez que l’émetteur utilise le magasin CA système. Pour External MQTT, vérifiez que les fichiers Certificat CA, Certificat client et Clé privée ont été téléversés en tant que fichiers séparés (et non collés en contenu PEM), et que la Clé privée était non chiffrée lors du téléversement. |
| `échec de l’authentification` / `non autorisé` | Identifiants incorrects | Revérifiez le nom d’utilisateur et le mot de passe. Pour Cloud MQTT, si le mot de passe a été perdu, faites-le tourner depuis les paramètres du connecteur (l’original n’est pas récupérable). Pour l’authentification de base sur External MQTT, vérifiez que le fichier de mots de passe du broker est correct. |
| `échec d’authentification (JWT)` | Problèmes de jeton | Vérifiez que le JWT est valide (non expiré), signé avec la bonne clé pour le validateur du broker, et qu’il contient les revendications requises (sujet, autorisations de topic). |
Pour les configurations reliées à Z2M en particulier, le journal Z2M affiche explicitement l’état de connexion :
```
docker compose logs zigbee2mqtt | grep -E "Connecting|Connected|MQTT|Error"
```
`Connecté au serveur MQTT` confirme le côté émetteur. L’absence de cette ligne indique un échec de phase 1, quel que soit ce qu’affiche la plateforme.
## Phase 2 — La connexion réussit mais Dernières données reçues ne se met pas à jour
**Symptôme :** l’émetteur signale une connexion réussie au broker. Les journaux montrent des publications réussies. **Dernières données reçues** dans la page du connecteur Kilo reste vide.
Pour Cloud MQTT, il s’agit d’une discordance du préfixe de topic. Chaque topic publié doit commencer exactement par le préfixe de topic du connecteur. Vérifiez :
* La configuration de topic de l’émetteur utilise le **préfixe complet** de topic de la page du connecteur (généralement `iot/{org}/{connection}`).
* Pour Z2M, `mqtt.base_topic` dans `configuration.yaml` est `{Topic prefix}/zigbee2mqtt`.
* Pour un firmware personnalisé, chaque appel de publication ajoute le préfixe.
Pour External MQTT, il s’agit d’un problème de joignabilité ou d’abonnement :
* Exécutez une publication de test unique depuis un hôte qui peut atteindre votre broker :
```bash
mosquitto_pub -h {broker-host} -p {port} \\
--cafile {ca-bundle} \\
-u {username} -P {password} \\
-t "test/connectivity" -m '{"hello":"world"}'
```
Si **Dernières données reçues** ne se met toujours pas à jour, la plateforme ne peut pas atteindre votre broker. Examinez les règles de pare-feu, les listes d’autorisation d’IP, ou les sessions de tunneling expirées lorsque vous utilisez ngrok pour les tests.
* Pour les brokers derrière un NAT avec redirection de port, vérifiez que le port externe est ouvert et redirigé vers le port hôte du broker. Les erreurs de configuration courantes incluent la redirection vers la mauvaise IP d’hôte, le blocage de l’IP source, ou une règle de pare-feu qui prend le pas sur la redirection de port.
## Phase 3 — Les Dernières données reçues se mettent à jour mais l’onglet Mapping de l’appareil est vide
**Symptôme :** le connecteur reçoit des messages (Dernières données reçues est à jour), mais la colonne Valeur de l’onglet Mapping d’un appareil enregistré n’affiche rien.
Deux causes sont fréquentes :
* **Le modèle de topic de l’ID d’appareil ne correspond pas au topic de publication.** Vérifiez le modèle en le comparant caractère par caractère à un topic issu des journaux de l’émetteur. Erreurs courantes : barre oblique initiale, segments intermédiaires manquants, casse différente, pluralité différente (`mètre` contre `mètres`).
* **L’ID de l’appareil est différent caractère par caractère du segment extrait.** La suppression des espaces dans le champ ID de l’appareil est ici le tueur silencieux. Si le topic de l’émetteur est `plant-3/line-a/EM 4492/data` (contenant un espace) et que l’ID de l’appareil a été saisi comme `EM 4492`, la plateforme a enregistré une chaîne normalisée qui ne correspond plus. Supprimez les espaces des identifiants d’appareil — utilisez des tirets ou des underscores. Recréez l’enregistrement de l’appareil avec l’identifiant normalisé.
Pour vérifier ce que l’émetteur envoie réellement :
```bash
# Pour Z2M :
docker compose logs zigbee2mqtt | grep "MQTT publish" | grep -v bridge | tail -5
# Pour les autres passerelles : abonnez-vous directement au broker
mosquitto_sub -h {broker} -p {port} -t '#' -v
```
Le topic affiché dans ces lignes de sortie est le topic auquel votre modèle de topic d’ID d’appareil et le champ ID d’appareil doivent correspondre.
## Phase 4 — La colonne Valeur de l’onglet Mapping se met à jour mais l’onglet Logs est vide
**Symptôme :** Ouvrez un appareil enregistré. L’onglet Mapping affiche des valeurs en direct et des horodatages de Dernière mise à jour. L’onglet Logs est vide.
C’est la confusion opérationnelle la plus courante lors de la mise en service d’un nouvel appareil MQTT. Les deux onglets lisent dans des stockages différents :
* **Colonne Valeur de l’onglet Mapping** = instantané en direct de la charge utile la plus récente. Se met à jour à chaque publication acceptée, que les clés du connecteur soient renseignées ou non.
* **Onglet Logs** = historique par capteur, alimenté uniquement par les publications reçues *après* l’enregistrement des clés du connecteur.
Si la publication la plus récente est arrivée avant l’enregistrement des clés du connecteur, cette publication n’atteint jamais les Logs. Les publications plus anciennes ne sont pas normalisées rétroactivement.
Résolution : générez une nouvelle publication après avoir enregistré les clés du connecteur. Méthodes :
* **Attendez la prochaine remontée planifiée de l’appareil** — pour les capteurs à cadence de publication périodique.
* **Déclenchez un changement d’état sur l’appareil** — pour les actionneurs avec sémantique COV au changement d’état.
* **Émettez une requête d’interrogation depuis la passerelle** — pour les passerelles avec un mécanisme de lecture/polling de type `/get`-style.
* **Envoyez une publication de test depuis le côté broker** — pour les scénarios de développement, `mosquitto_pub` vers le topic de l’appareil avec une charge utile représentative.
Après qu’au moins une publication est arrivée après l’enregistrement, l’onglet Logs se remplit et continue de recevoir le trafic suivant.
## Phase 5 — valeurs nulles dans la colonne Valeur de l’onglet Mapping
**Symptôme :** Les clés du connecteur sont mappées, l’onglet Logs reçoit des données, mais certaines valeurs de métriques apparaissent comme null dans l’onglet Mapping.
La cause la plus courante : le Type du modèle de métrique ne correspond pas au type de la valeur publiée. Par exemple, associer un champ Z2M `state` (`"ON"`/`"OFF"` chaînes) à un modèle de métrique typé Booléen entraîne des valeurs nulles — la plateforme ne peut pas analyser la chaîne comme un booléen.
Vérifiez la [translation du type de charge utile vers le type de métrique](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md#payload-type--metric-type-translation):
* Les énumérations codées en chaîne (par ex. `"OPEN"`/`"CLOSED"`, `"ON"`/`"OFF"`) → **Chaîne**, pas Booléen.
* Z2M `binaires` caractéristiques → Chaîne. Z2M `numériques` caractéristiques → Nombre. Z2M `énumérées` caractéristiques → Chaîne.
Résolution : modifiez le modèle de métrique (ou remplacez la ligne de Mapping par une ligne utilisant le bon type de modèle) afin que le Type corresponde au type réel de la valeur de la charge utile.
## Phase 6 — Valeurs de métriques incohérentes ou dupliquées sur plusieurs appareils
**Symptôme :** deux enregistrements d’appareil semblent recevoir la télémétrie l’un de l’autre, ou un seul appareil affiche des valeurs alternant entre différentes sources.
Il s’agit d’une collision de modèle de topic de l’ID d’appareil. Si deux appareils publient sur des topics qui correspondent tous deux à un seul modèle de topic d’ID d’appareil à des `{{deviceId}}` valeurs, mais que le champ ID de l’appareil sur un enregistrement correspond aux deux, les deux publications sont routées vers cet enregistrement.
Vérifiez :
* Chaque enregistrement d’appareil a un ID d’appareil unique.
* Les topics côté publication produisent des valeurs uniques à la position du `{{deviceId}}` placeholder.
* Aucun émetteur n’est mal configuré pour publier sous l’identifiant d’un autre appareil.
## Réinitialisation des identifiants Cloud MQTT
Lorsqu’un identifiant doit être renouvelé :
1. Ouvrez la page de détail du connecteur.
2. En mode édition, régénérez le mot de passe.
3. Capturez immédiatement le nouveau mot de passe ; l’original n’est pas récupérable après régénération.
4. Mettez à jour tous les clients émetteurs (configuration du firmware, Z2M `configuration.yaml`, configuration de la passerelle de périphérie) avec le nouveau mot de passe.
5. Redémarrez les émetteurs pour prendre en compte la rotation.
Le nom d’utilisateur et le préfixe de topic ne changent pas lors de la rotation.
## Réinitialisation des identifiants External MQTT
Pour l’authentification de base, changez le mot de passe côté broker et mettez à jour la configuration d’authentification du connecteur. Pour la certification (certificat client TLS), réémettez le certificat client et téléversez-le à nouveau. Pour JWT, régénérez le jeton et mettez à jour le connecteur. Dans tous les cas, il n’existe pas de flux de rotation des identifiants côté plateforme — l’identifiant se trouve sur le broker ; la plateforme stocke une référence.
## Où aller ensuite
* [Topics et routage des appareils](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) — pour les détails de configuration du routage.
* [External MQTT](/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/external-mqtt.md) — pour la configuration côté broker des brokers auto-hébergés.
* [Passerelles Edge MQTT](/kilo-docs-fr/kilo-iot-server/gateways/mqtt-edge-gateways.md) — pour les schémas d’intégration des passerelles industrielles de périphérie (dans Passerelles).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-fr/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
