> 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-es/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md).
# Solución de problemas
Soluciona problemas de integraciones MQTT por fase de fallo — conexión al broker, TLS, autenticación, enrutamiento de topics, últimos datos.
Recetas de diagnóstico para integraciones MQTT en el Kilo IoT Server, organizadas según dónde se manifiesta la falla. Recorre esto en orden: la mayoría de los problemas caen en una de las tres primeras fases, y la secuencia de diagnóstico acota eficientemente la causa raíz.
Antes de recorrer las fases a continuación, deja que la plataforma te indique en cuál estás. Un solo dispositivo en silencio informa su propio estado en su **Conexión** pestaña — si el broker es accesible, si llegó una publicación en un tema inesperado y si sus valores se almacenaron; consulta [Diagnóstico del dispositivo](/kilo-docs-es/kilo-iot-server/devices/device-diagnostics.md). Cuando varios dispositivos se callan a la vez, abre el **Diagnósticos del conector** área — **Estado de la fuente** resume la suscripción al broker, **Entrante** muestra lo que está llegando, y **Actividad** muestra el historial reciente de eventos del conector. Esa lectura normalmente apunta directamente a la fase desde la que empezar.
## Fase 1 — Fallos de conexión con el broker
**Síntoma:** el publicador (una pasarela de borde, una instancia de Zigbee2MQTT, firmware personalizado) informa que no puede conectarse al broker. **Últimos datos recibidos** nunca se actualiza.
| Patrón de fallo | Causa raíz | Resolución |
| ---------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `conexión rechazada` / `red inalcanzable` (Cloud MQTT) | Host, puerto o esquema incorrectos | Verifica que el publicador use `mqtts://` en el puerto 1884, no el 1883 predeterminado. Vuelve a copiar la URL del broker desde la página del conector. |
| `conexión rechazada` / `red inalcanzable` (External MQTT) | Accesibilidad de red | La plataforma se conecta hacia fuera a tu broker. Verifica que el broker sea accesible desde Internet pública (el nombre de host DDNS resuelve, el reenvío de puertos está activo, el firewall permite el rango de salida de la plataforma). |
| `intercambio TLS incorrecto` / `falló la verificación del certificado` | Configuración TLS | Para Cloud MQTT, el certificado es de confianza pública: verifica que el publicador use el almacén de CA del sistema. Para External MQTT, verifica que los archivos Certificado CA, Certificado de cliente y Clave privada se hayan cargado como archivos separados (no contenido PEM pegado), y que la clave privada estuviera sin cifrar al cargarla. |
| `falló la autenticación` / `no autorizado` | Credenciales incorrectas | Vuelve a verificar Nombre de usuario y Contraseña. Para Cloud MQTT, si se perdió la contraseña, rótala desde la configuración del conector (la original no se puede recuperar). Para autenticación básica en External MQTT, comprueba que el archivo de contraseñas del broker sea correcto. |
| `falló la autenticación (JWT)` | Problemas con el token | Verifica que el JWT sea válido (no esté expirado), esté firmado con la clave correcta para el validador del broker y tenga las claims requeridas (subject, permisos de tema). |
Para configuraciones con puente Z2M, el registro de Z2M muestra explícitamente el estado de conexión:
```
docker compose logs zigbee2mqtt | grep -E "Connecting|Connected|MQTT|Error"
```
`Conectado al servidor MQTT` confirma el lado del publicador. La ausencia de esa línea indica un fallo de la Fase 1, independientemente de lo que muestre la plataforma.
## Fase 2 — La conexión se establece pero Últimos datos recibidos no se actualiza
**Síntoma:** el publicador informa una conexión exitosa con el broker. Los registros muestran publicaciones correctas. **Últimos datos recibidos** en la página del conector Kilo permanece vacío.
Para Cloud MQTT, esto es una discrepancia en el prefijo del tema. Todo tema publicado debe comenzar exactamente con el prefijo de tema del conector. Verifica:
* La configuración de tema del publicador usa el **completo** prefijo de tema de la página del conector (normalmente `iot/{org}/{connection}`).
* Para Z2M, `mqtt.base_topic` en `configuration.yaml` es `{Topic prefix}/zigbee2mqtt`.
* Para firmware personalizado, cada llamada de publicación antepone el prefijo.
Para External MQTT, esto es una discrepancia de accesibilidad o de suscripción:
* Ejecuta una publicación de prueba única desde un host que pueda الوصول a tu broker:
```bash
mosquitto_pub -h {broker-host} -p {port} \
--cafile {ca-bundle} \
-u {username} -P {password} \
-t "test/connectivity" -m '{"hello":"world"}'
```
Si **Últimos datos recibidos** sigue sin actualizarse, la plataforma no puede acceder a tu broker. Investiga las reglas de firewall, listas de अनुमति de IP o sesiones de túnel caducadas cuando uses ngrok para pruebas.
* Para brokers detrás de NAT con reenvío de puertos, verifica que el puerto externo esté abierto y reenviado al puerto del host del broker. Los errores de configuración comunes incluyen reenviar al IP de host equivocado, bloquear la IP de origen o tener una regla de firewall que sustituya al reenvío de puertos.
## Fase 3 — Últimos datos recibidos se actualiza pero la pestaña Mapping del dispositivo está vacía
**Síntoma:** el conector recibe mensajes (Últimos datos recibidos está actualizado), pero la columna Value de la pestaña Mapping de un dispositivo registrado no muestra nada.
Son comunes dos causas:
* **El patrón de tema del Device ID no coincide con el tema publicado.** Verifica el patrón comparándolo byte a byte con un tema de los registros del publicador. Errores comunes: barra inicial, segmentos intermedios faltantes, mayúsculas/minúsculas distintas, pluralidad distinta (`metro` frente a `metros`).
* **El Device ID es byte a byte diferente del segmento extraído.** La eliminación de espacios en blanco en la entrada del Device ID es el asesino silencioso aquí. Si el tema del publicador es `plant-3/line-a/EM 4492/data` (que contiene un espacio) y el Device ID se escribió como `EM 4492`, la plataforma almacenó una cadena normalizada que ya no coincide. Elimina los espacios en blanco de los identificadores de dispositivos: usa guiones o guiones bajos. Vuelve a crear el registro del dispositivo con el identificador normalizado.
Para verificar lo que el publicador está enviando realmente:
```bash
# Para Z2M:
docker compose logs zigbee2mqtt | grep "MQTT publish" | grep -v bridge | tail -5
# Para otras pasarelas: suscríbete directamente al broker
mosquitto_sub -h {broker} -p {port} -t '#' -v
```
El tema mostrado en esas líneas de salida es el tema con el que tu patrón de tema de Device ID y el campo Device ID deben coincidir.
## Fase 4 — La columna Value de la pestaña Mapping se actualiza pero la pestaña Logs está vacía
**Síntoma:** Abre un dispositivo registrado. La pestaña Mapping muestra valores en vivo y marcas de tiempo de Última actualización. La pestaña Logs está vacía.
Esta es la confusión operativa más común al poner en marcha un nuevo dispositivo MQTT. Las dos pestañas leen de almacenes diferentes:
* **columna Value de la pestaña Mapping** = instantánea en vivo de la carga útil más reciente. Se actualiza en cada publicación aceptada, independientemente de si las claves del conector están pobladas.
* **Pestaña Registros** = historial por sensor, poblado solo por publicaciones recibidas *después de* Las claves del conector están guardadas.
Si la publicación más reciente llegó antes de que se guardaran las claves del conector, esa publicación nunca llega a Logs. Las publicaciones anteriores no se normalizan retroactivamente.
Resolución: genera una nueva publicación después de guardar las claves del conector. Métodos:
* **Espera el siguiente informe programado del dispositivo** — para sensores con un ciclo de publicación periódico.
* **Provoca un cambio de estado en el dispositivo** — para actuadores con semántica COV al cambio de estado.
* **Emite una solicitud de sondeo desde la pasarela** — para pasarelas con un mecanismo de sondeo de lectura tipo `/get`.
* **Envía una publicación de prueba desde el lado del broker** — para escenarios de desarrollo, `mosquitto_pub` al tema del dispositivo con una carga útil representativa.
Después de que llegue al menos una publicación tras guardar, la pestaña Logs se rellena y continúa recibiendo tráfico posterior.
## Fase 5 — valores null en la columna Value de la pestaña Mapping
**Síntoma:** Las claves del conector están mapeadas, la pestaña Logs está recibiendo datos, pero valores de métricas específicos aparecen como null en la pestaña Mapping.
La causa más común: el Type de la plantilla de métrica no coincide con el tipo del valor publicado. Por ejemplo, mapear un campo Z2M `state` campo (`"ON"`/`"OFF"` cadenas) a una plantilla de métrica de tipo Boolean produce null: la plataforma no puede analizar la cadena como booleano.
Revise la pestaña [traducción de tipo de carga útil → tipo de métrica](/kilo-docs-es/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md#payload-type--metric-type-translation):
* Enums codificados como cadena (p. ej. `"OPEN"`/`"CLOSED"`, `"ON"`/`"OFF"`) → **String**, no Boolean.
* Z2M `funciones` binarias → String. Z2M `funciones` numéricas → Number. Z2M `funciones` enum → String.
Resolución: edita la plantilla de la métrica (o reemplaza la fila de Mapping por una fila que use el tipo de plantilla correcto) para que el Type coincida con el tipo real del valor de la carga útil.
## Fase 6 — valores de métricas inconsistentes o duplicados en varios dispositivos
**Síntoma:** dos registros de dispositivo parecen recibir la telemetría del otro, o un solo dispositivo muestra valores alternos de distintas fuentes.
Esto es una colisión del patrón de tema del Device ID. Si dos dispositivos publican en temas que ambos coinciden con un solo patrón de tema del Device ID en diferentes `{{deviceId}}` valores, pero el campo Device ID de uno de los registros del dispositivo coincide con ambos, ambas publicaciones se enrutan a ese registro.
Verifica:
* Cada registro de dispositivo tiene un Device ID único.
* Los temas del lado del publicador producen valores únicos en la posición del `{{deviceId}}` marcador de posición.
* Ningún publicador está mal configurado para publicar bajo el identificador de otro dispositivo.
## Restablecimiento de credenciales de Cloud MQTT
Cuando una credencial necesita rotarse:
1. Abre la página de detalles del conector.
2. En modo edición, regenera la contraseña.
3. Captura la nueva contraseña de inmediato; la original no se puede recuperar después de regenerarla.
4. Actualiza todos los clientes publicadores (configuración del firmware, Z2M `configuration.yaml`, configuración de la pasarela de borde) con la nueva contraseña.
5. Reinicia los publicadores para que tomen la rotación.
El nombre de usuario y el prefijo de tema no cambian al rotar.
## Restablecimiento de credenciales de External MQTT
Para autenticación básica, cambia la contraseña del lado del broker y actualiza la configuración de autenticación del conector. Para Certification (certificado de cliente TLS), vuelve a emitir el certificado de cliente y súbelo de nuevo. Para JWT, regenera el token y actualiza el conector. En todos los casos, no existe un flujo de rotación de credenciales del lado de la plataforma: la credencial está en el broker; la plataforma almacena una referencia.
## A dónde ir a continuación
* [Temas y enrutamiento de dispositivos](/kilo-docs-es/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) — para detalles de configuración de enrutamiento.
* [MQTT externo](/kilo-docs-es/kilo-iot-server/connectors/mqtt-connector/external-mqtt.md) — para la configuración del lado del broker de brokers autohospedados.
* [Pasarelas MQTT Edge](/kilo-docs-es/kilo-iot-server/gateways/mqtt-edge-gateways.md) — para patrones de integración de pasarelas de borde industriales (en Pasarelas).
---
# 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-es/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.
