Buscador de códigos de motivo MQTT
¿Te ha llegado un 0x87, un 135 o “Connection refused: not authorized”? Busca entre todos los reason codes de MQTT 5 y return codes de MQTT 3.1.1 para ver qué significan y cómo solucionarlos.
- CONNACK
El servidor rechazó el nombre de usuario o la contraseña.
Cómo solucionarlo: Revisa las credenciales (atención a los espacios al final y a las mayúsculas) y confirma que el usuario existe en el archivo de contraseñas o en el backend de autenticación del broker.
Consejo: las credenciales por usuario y las ACL por topic son más fáciles de configurar bien cuando controlas el broker. ConnectMQ te permite gestionar ambas desde un panel.
- CONNACKPUBACKPUBRECSUBACKUNSUBACKDISCONNECT
El cliente no tiene permiso para hacer esto: conectarse, publicar en ese topic o suscribirse a ese filtro.
Cómo solucionarlo: Revisa la ACL del broker para este usuario y topic. En CONNACK suele significar que el acceso anónimo está desactivado y no se enviaron credenciales.
Consejo: las credenciales por usuario y las ACL por topic son más fáciles de configurar bien cuando controlas el broker. ConnectMQ te permite gestionar ambas desde un panel.
- CONNACK
El client ID está bien formado, pero el servidor no lo acepta (demasiado largo, caracteres no válidos o vacío cuando no se permite).
Cómo solucionarlo: Usa un client ID alfanumérico corto (hasta 23 caracteres siempre es seguro) o deja que el broker asigne uno enviando un ID vacío con clean start.
- DISCONNECT
Otra conexión con el mismo client ID se ha conectado, así que esta ha sido expulsada.
Cómo solucionarlo: Asigna un client ID único a cada dispositivo y a cada pestaña del navegador. Dos clientes que comparten ID se desconectan mutuamente en bucle.
- DISCONNECT
No se recibió ningún paquete en 1,5 × el intervalo de keep alive, así que se cerró la conexión.
Cómo solucionarlo: Asegúrate de que el bucle de tu cliente se ejecuta (se envía PINGREQ), no bloquees el hilo de red o aumenta el intervalo de keep alive.
- CONNACKPUBACKPUBRECSUBACKUNSUBACKDISCONNECT
Algo ha fallado y el servidor no quiere (o no puede) decir qué.
Cómo solucionarlo: Revisa los logs del broker: normalmente contienen la causa real. Mira también la propiedad Reason String si se envió.
- CONNACKPUBACKPUBRECSUBACKDISCONNECT
Se ha superado una cuota de la implementación o administrativa (mensajes, conexiones, almacenamiento…).
Cómo solucionarlo: Revisa tu plan o las cuotas del broker, reduce el volumen de mensajes o pide al operador que aumente el límite.
Consejo: las credenciales por usuario y las ACL por topic son más fáciles de configurar bien cuando controlas el broker. ConnectMQ te permite gestionar ambas desde un panel.
- 5Connection Refused, not authorized · Conexión rechazada, no autorizadoMQTT 3.1.1 · return code de CONNACKCONNACK
El cliente no está autorizado para conectarse.
Cómo solucionarlo: Envía credenciales si el acceso anónimo está desactivado y revisa la ACL del broker para este usuario.
Consejo: las credenciales por usuario y las ACL por topic son más fáciles de configurar bien cuando controlas el broker. ConnectMQ te permite gestionar ambas desde un panel.
Cómo funcionan los códigos de motivo MQTT
Un reason code (código de motivo) es un único byte que el broker (o el cliente) devuelve para indicar cómo ha ido una operación. En MQTT 5 aparecen en CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT y AUTH. La regla es sencilla: los valores por debajo de 0x80 indican éxito (a veces con información adicional, como 0x10 No matching subscribers) y los valores de 0x80 en adelante indican un fallo. El mismo número tiene el mismo significado en todos los paquetes en los que está permitido, así que 0x87 siempre es “Not authorized”, tanto si llega en una conexión como en una publicación o una suscripción.
MQTT 3.1.1 es mucho menos expresivo. Solo CONNACK lleva un return code (0–5) y SUBACK solo puede indicar “QoS 0/1/2 concedido” o 0x80 Failure. Una publicación QoS 0 rechazada se descarta sin aviso, y muchos brokers simplemente cierran la conexión TCP ante un error, por lo que el log del broker suele ser tu única pista. Si necesitas informes de error precisos, merece la pena pasarse a MQTT 5.
Cómo leer los códigos que muestra tu librería
Cada librería cliente muestra los códigos a su manera. Paho Python muestra valores decimales (rc=135), MQTT.js suele mostrar el número decimal junto con un mensaje y las herramientas de línea de comandos de Mosquitto imprimen textos como “Connection Refused: not authorised”. El buscador de arriba acepta todos estos formatos: escribe 135, 0x87, 87 o una frase como keep alive. En MQTT 5 el broker también puede incluir la propiedad Reason String con una explicación legible: regístrala en tus logs, porque suele ser más específica que el propio código.
Los errores que verás con más frecuencia
- 0x86 / return code 4: usuario o contraseña incorrectos. Revisa erratas, espacios al final y mayúsculas/minúsculas. Consulta la guía de autenticación de Mosquitto para configurar archivos de contraseñas.
- 0x87 / return code 5: no autorizado. Puede que las credenciales sean correctas pero la ACL bloquee el topic, o que el broker rechace clientes anónimos.
- 0x8E: sesión tomada por otro cliente. Dos clientes comparten el mismo client ID. Genera IDs únicos con el generador de Client ID.
- 0x8D: timeout de keep alive. El cliente dejó de enviar paquetes. Lee cómo funciona el keep alive de MQTT.
- 0x95: paquete demasiado grande. Comprueba el tamaño de tu mensaje con la calculadora de tamaño de paquete.
Muchos problemas de conexión ni siquiera llegan a generar un reason code: los fallos de DNS, los puertos incorrectos y los errores del handshake TLS ocurren antes de que empiece MQTT. Para esos casos, consulta los errores de conexión MQTT más comunes y la referencia de puertos MQTT, o reproduce el problema en el cliente MQTT online, que muestra el resultado del CONNACK en su log.
Todos los reason codes de MQTT 5
Todos los reason codes definidos en la sección 2.4 de la especificación OASIS MQTT 5.0. Enlaza a un código con #0x87.
| Código | Nombre | Paquetes | Significado y solución |
|---|---|---|---|
| 0x00 dec 0 | Success Éxito | CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, UNSUBACK, AUTH | La operación se completó correctamente. Solución: No hay nada que solucionar: es el resultado normal. |
| 0x00 dec 0 | Normal disconnection Desconexión normal | DISCONNECT | La conexión se cerró de forma intencionada y no se envía el Will Message. Solución: No hay nada que solucionar. Si no esperabas la desconexión, comprueba qué lado la envió y por qué. |
| 0x00 dec 0 | Granted QoS 0 QoS 0 concedido | SUBACK | La suscripción se aceptó con una QoS máxima de 0. Solución: Si pediste QoS 1 o 2, el broker la ha rebajado: revisa su ajuste de QoS máxima. |
| 0x01 dec 1 | Granted QoS 1 QoS 1 concedido | SUBACK | La suscripción se aceptó con una QoS máxima de 1. Solución: Si pediste QoS 2, el broker limita la QoS a 1: diseña para una entrega at-least-once (handlers idempotentes). |
| 0x02 dec 2 | Granted QoS 2 QoS 2 concedido | SUBACK | La suscripción se aceptó con una QoS máxima de 2. Solución: No hay nada que solucionar: obtienes la entrega exactly-once que pediste. |
| 0x04 dec 4 | Disconnect with Will Message Desconexión con Will Message | DISCONNECT | El cliente quiere desconectarse, pero pide al servidor que publique igualmente su Will Message. Solución: No hay nada que solucionar: es una decisión deliberada del cliente. |
| 0x10 dec 16 | No matching subscribers No hay suscriptores coincidentes | PUBACK, PUBREC | El mensaje se aceptó, pero ahora mismo nadie está suscrito a ese topic. Solución: No es un error. Comprueba que el suscriptor esté conectado y que su filtro de topic coincida exactamente con el topic (distingue mayúsculas y minúsculas). |
| 0x11 dec 17 | No subscription existed No existía la suscripción | UNSUBACK | El cliente intentó cancelar la suscripción a un filtro de topic al que no estaba suscrito. Solución: Asegúrate de que el filtro del unsubscribe sea idéntico, byte a byte, al que usaste al suscribirte. |
| 0x18 dec 24 | Continue authentication Continuar la autenticación | AUTH | La autenticación mejorada está en curso y se necesita otro paso AUTH. Solución: Tu cliente debe responder con un paquete AUTH que contenga el siguiente paso del método de autenticación. |
| 0x19 dec 25 | Re-authenticate Volver a autenticar | AUTH | El cliente pide repetir la autenticación mejorada en una conexión existente. Solución: No hay nada que solucionar: se usa para renovar credenciales, como tokens que caducan. |
| 0x80 dec 128 | Unspecified error Error no especificado | CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT | Algo ha fallado y el servidor no quiere (o no puede) decir qué. Solución: Revisa los logs del broker: normalmente contienen la causa real. Mira también la propiedad Reason String si se envió. |
| 0x81 dec 129 | Malformed Packet Paquete mal formado | CONNACK, DISCONNECT | El paquete recibido no cumple la especificación MQTT y no se pudo analizar. Solución: Actualiza tu librería cliente, asegúrate de que la versión del protocolo coincide y comprueba que no estás hablando MQTT con un puerto que no es MQTT (o TCP sin cifrar con un puerto TLS). |
| 0x82 dec 130 | Protocol Error Error de protocolo | CONNACK, DISCONNECT | El paquete se analizó correctamente pero incumple una regla del protocolo, p. ej. un segundo CONNECT o una propiedad duplicada. Solución: Suele ser un bug de la librería cliente o de código propio que construye paquetes. Actualiza la librería y evita enviar paquetes fuera de orden. |
| 0x83 dec 131 | Implementation specific error Error específico de la implementación | CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT | El paquete es válido, pero el servidor lo rechaza por un motivo propio del broker. Solución: Lee el Reason String y la documentación o los logs del broker: la causa depende del broker (plugins, límites, políticas). |
| 0x84 dec 132 | Unsupported Protocol Version Versión de protocolo no soportada | CONNACK | El servidor no admite la versión del protocolo MQTT que solicitó el cliente. Solución: Cambia el cliente a MQTT 3.1.1 (protocol level 4) o actualiza a un broker compatible con MQTT 5. |
| 0x85 dec 133 | Client Identifier not valid Identificador de cliente no válido | CONNACK | El client ID está bien formado, pero el servidor no lo acepta (demasiado largo, caracteres no válidos o vacío cuando no se permite). Solución: Usa un client ID alfanumérico corto (hasta 23 caracteres siempre es seguro) o deja que el broker asigne uno enviando un ID vacío con clean start. |
| 0x86 dec 134 | Bad User Name or Password Usuario o contraseña incorrectos | CONNACK | El servidor rechazó el nombre de usuario o la contraseña. Solución: Revisa las credenciales (atención a los espacios al final y a las mayúsculas) y confirma que el usuario existe en el archivo de contraseñas o en el backend de autenticación del broker. |
| 0x87 dec 135 | Not authorized No autorizado | CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT | El cliente no tiene permiso para hacer esto: conectarse, publicar en ese topic o suscribirse a ese filtro. Solución: Revisa la ACL del broker para este usuario y topic. En CONNACK suele significar que el acceso anónimo está desactivado y no se enviaron credenciales. |
| 0x88 dec 136 | Server unavailable Servidor no disponible | CONNACK | El servidor MQTT no está disponible en este momento. Solución: Reintenta con backoff exponencial. Si persiste, revisa el estado del broker, el estado del clúster y las ventanas de mantenimiento. |
| 0x89 dec 137 | Server busy Servidor ocupado | CONNACK, DISCONNECT | El servidor está sobrecargado y rechaza la operación; inténtalo más tarde. Solución: Espera y reintenta con jitter para que miles de dispositivos no se reconecten en el mismo instante. |
| 0x8A dec 138 | Banned Bloqueado | CONNACK | Este cliente ha sido bloqueado por una acción administrativa. Solución: Contacta con el operador del broker. Los inicios de sesión fallidos repetidos o el tráfico abusivo son motivos habituales de bloqueo. |
| 0x8B dec 139 | Server shutting down Servidor apagándose | DISCONNECT | El servidor se está apagando. Solución: Reconecta con backoff; usa una sesión persistente para que las suscripciones y los mensajes QoS 1/2 en cola se conserven. |
| 0x8C dec 140 | Bad authentication method Método de autenticación incorrecto | CONNACK, DISCONNECT | El método de autenticación de CONNECT no está soportado o no coincide con el que se está usando. Solución: Elimina la propiedad Authentication Method o establécela en un método que admita el broker (p. ej. SCRAM-SHA-256). |
| 0x8D dec 141 | Keep Alive timeout Tiempo de keep alive agotado | DISCONNECT | No se recibió ningún paquete en 1,5 × el intervalo de keep alive, así que se cerró la conexión. Solución: Asegúrate de que el bucle de tu cliente se ejecuta (se envía PINGREQ), no bloquees el hilo de red o aumenta el intervalo de keep alive. |
| 0x8E dec 142 | Session taken over Sesión tomada por otra conexión | DISCONNECT | Otra conexión con el mismo client ID se ha conectado, así que esta ha sido expulsada. Solución: Asigna un client ID único a cada dispositivo y a cada pestaña del navegador. Dos clientes que comparten ID se desconectan mutuamente en bucle. |
| 0x8F dec 143 | Topic Filter invalid Filtro de topic no válido | SUBACK, UNSUBACK, DISCONNECT | El filtro de topic está bien formado, pero este servidor no lo acepta. Solución: Revisa la posición de los comodines (+ debe ocupar un nivel completo y # debe ir al final) y los límites del broker sobre profundidad o longitud de topics. |
| 0x90 dec 144 | Topic Name invalid Nombre de topic no válido | CONNACK, PUBACK, PUBREC, DISCONNECT | El nombre del topic está bien formado, pero el cliente o el servidor no lo acepta. Solución: Nunca publiques en un topic que contenga + o #, evita los topics vacíos y revisa los límites de longitud y profundidad de topics del broker. |
| 0x91 dec 145 | Packet Identifier in use Identificador de paquete en uso | PUBACK, PUBREC, SUBACK, UNSUBACK | El identificador de paquete ya se está usando en otro intercambio en curso. Solución: Suele ser un bug de la librería cliente o una sesión restaurada de forma inconsistente. Actualiza la librería o inicia una sesión limpia. |
| 0x92 dec 146 | Packet Identifier not found Identificador de paquete no encontrado | PUBREL, PUBCOMP | El identificador de paquete no es conocido: se ha perdido el estado del flujo QoS 2. Solución: Ocurre cuando se pierde el estado de la sesión (p. ej. clean start o reinicio del broker sin persistencia). Activa la persistencia en el broker. |
| 0x93 dec 147 | Receive Maximum exceeded Receive Maximum superado | DISCONNECT | Se enviaron más paquetes PUBLISH QoS 1/2 sin confirmar de los que permite el receptor. Solución: Respeta el Receive Maximum de CONNACK/CONNECT; limita los mensajes en vuelo en la configuración de tu cliente. |
| 0x94 dec 148 | Topic Alias invalid Topic Alias no válido | DISCONNECT | Un topic alias era 0, mayor que el Topic Alias Maximum o se usó antes de definirse. Solución: Respeta el Topic Alias Maximum que anunció el otro extremo o desactiva los topic aliases. |
| 0x95 dec 149 | Packet too large Paquete demasiado grande | CONNACK, DISCONNECT | El paquete supera el tamaño máximo de paquete permitido por el receptor. Solución: Reduce el payload (comprímelo, divídelo o envía una referencia) o aumenta el límite de tamaño de mensaje del broker. |
| 0x96 dec 150 | Message rate too high Tasa de mensajes demasiado alta | DISCONNECT | El cliente publica más rápido de lo que permite el servidor. Solución: Limita la frecuencia de publicación, agrupa las lecturas en menos mensajes o aumenta el límite de tasa en el broker. |
| 0x97 dec 151 | Quota exceeded Cuota superada | CONNACK, PUBACK, PUBREC, SUBACK, DISCONNECT | Se ha superado una cuota de la implementación o administrativa (mensajes, conexiones, almacenamiento…). Solución: Revisa tu plan o las cuotas del broker, reduce el volumen de mensajes o pide al operador que aumente el límite. |
| 0x98 dec 152 | Administrative action Acción administrativa | DISCONNECT | Un administrador cerró la conexión. Solución: Contacta con el operador del broker: alguien expulsó a este cliente manualmente o mediante una API de administración. |
| 0x99 dec 153 | Payload format invalid Formato de payload no válido | CONNACK, PUBACK, PUBREC, DISCONNECT | El payload no coincide con el Payload Format Indicator (p. ej. marcado como UTF-8 pero no es UTF-8 válido). Solución: Establece Payload Format Indicator = 1 solo cuando el payload sea texto UTF-8 válido; envía los datos binarios sin él. |
| 0x9A dec 154 | Retain not supported Retain no soportado | CONNACK, DISCONNECT | El servidor no admite mensajes retenidos, pero el cliente envió uno. Solución: Quita el flag retain de las publicaciones y del Will Message, o usa un broker que admita retain. |
| 0x9B dec 155 | QoS not supported QoS no soportada | CONNACK, DISCONNECT | El cliente usó una QoS superior al Maximum QoS que el servidor anunció en CONNACK. Solución: Lee el Maximum QoS de CONNACK y publica (y configura la Will QoS) con un valor igual o inferior. |
| 0x9C dec 156 | Use another server Usa otro servidor | CONNACK, DISCONNECT | El cliente debe usar temporalmente otro servidor. Solución: Lee la propiedad Server Reference y conéctate allí; admite redirecciones en tu cliente si trabajas con clústeres. |
| 0x9D dec 157 | Server moved Servidor trasladado | CONNACK, DISCONNECT | El servidor se ha trasladado de forma permanente; el cliente debe usar otro servidor. Solución: Actualiza el hostname del broker en tu configuración usando la propiedad Server Reference. |
| 0x9E dec 158 | Shared Subscriptions not supported Suscripciones compartidas no soportadas | SUBACK, DISCONNECT | El servidor no admite suscripciones compartidas $share/…. Solución: Usa suscripciones normales o un broker con soporte de suscripciones compartidas para consumidores con balanceo de carga. |
| 0x9F dec 159 | Connection rate exceeded Tasa de conexión superada | CONNACK, DISCONNECT | El cliente se conecta con demasiada frecuencia; se alcanzó el límite de tasa de conexión. Solución: Añade backoff exponencial con jitter a las reconexiones y busca un bucle de reconexión (a menudo causado por client IDs duplicados). |
| 0xA0 dec 160 | Maximum connect time Tiempo máximo de conexión | DISCONNECT | Se ha alcanzado el tiempo máximo de conexión permitido para este cliente. Solución: Vuelve a conectarte; considera una sesión persistente para no perder nada durante la breve reconexión. |
| 0xA1 dec 161 | Subscription Identifiers not supported Identificadores de suscripción no soportados | SUBACK, DISCONNECT | El servidor no admite la propiedad Subscription Identifier. Solución: Elimina el Subscription Identifier de SUBSCRIBE y enruta los mensajes por topic. |
| 0xA2 dec 162 | Wildcard Subscriptions not supported Suscripciones con comodines no soportadas | SUBACK, DISCONNECT | El servidor no admite suscripciones que contengan los comodines + o #. Solución: Suscríbete a nombres de topic exactos o usa un broker que admita suscripciones con comodines. |
Return codes de MQTT 3.1.1
Return codes 0–5 de CONNACK y el código de fallo de SUBACK según la especificación MQTT 3.1.1.
| Código | Nombre | Paquetes | Significado y solución |
|---|---|---|---|
| 0 dec 0 | Connection Accepted Conexión aceptada | CONNACK | El broker aceptó la conexión. Solución: No hay nada que solucionar. |
| 1 dec 1 | Connection Refused, unacceptable protocol version Conexión rechazada, versión de protocolo no aceptable | CONNACK | El broker no admite el nivel de protocolo solicitado por el cliente. Solución: Configura el cliente en MQTT 3.1.1 (level 4) o 3.1 (level 3) para que coincida con el broker. |
| 2 dec 2 | Connection Refused, identifier rejected Conexión rechazada, identificador rechazado | CONNACK | El client ID es UTF-8 válido, pero el broker no lo permite. Solución: Usa entre 1 y 23 caracteres de [0-9a-zA-Z] o envía un ID vacío con clean session = true. |
| 3 dec 3 | Connection Refused, server unavailable Conexión rechazada, servidor no disponible | CONNACK | La conexión de red funcionó, pero el servicio MQTT no está disponible. Solución: Reintenta con backoff y revisa el estado del broker. |
| 4 dec 4 | Connection Refused, bad user name or password Conexión rechazada, usuario o contraseña incorrectos | CONNACK | El nombre de usuario o la contraseña están mal formados o son incorrectos. Solución: Verifica las credenciales y que el usuario exista en el backend de autenticación del broker. |
| 5 dec 5 | Connection Refused, not authorized Conexión rechazada, no autorizado | CONNACK | El cliente no está autorizado para conectarse. Solución: Envía credenciales si el acceso anónimo está desactivado y revisa la ACL del broker para este usuario. |
| 0x80 dec 128 | Failure Fallo | SUBACK | La suscripción fue rechazada, normalmente por una ACL o un filtro de topic no válido. Solución: Revisa la sintaxis del filtro y que el usuario tenga permiso para suscribirse a él. MQTT 3.1.1 no da más detalles; consulta el log del broker. |
Preguntas frecuentes sobre reason codes
¿Qué significa el reason code MQTT 0x87 (135)?
0x87 significa Not authorized (no autorizado). En CONNACK, el broker rechazó la conexión (a menudo porque el acceso anónimo está desactivado y no se enviaron credenciales). En PUBACK, SUBACK o DISCONNECT significa que el usuario no tiene permiso sobre ese topic en la ACL del broker.
¿Qué diferencia hay entre un reason code y un return code?
MQTT 3.1.1 solo tiene return codes en CONNACK (0–5) y SUBACK (0x00–0x02 y 0x80). MQTT 5 los sustituyó por reason codes que aparecen en casi todos los acuses de recibo, en DISCONNECT y en AUTH, y los valores de 0x80 o superiores siempre indican un fallo.
¿Por qué mi cliente se desconecta una y otra vez con 0x8E Session taken over?
Hay dos conexiones usando el mismo client ID. Cuando se conecta la segunda, el broker desconecta la primera. Si ambas se reconectan automáticamente, se expulsan mutuamente en bucle. Asigna un client ID único a cada dispositivo y a cada pestaña del navegador.
¿Por qué recibo el return code 5 en MQTT 3.1.1?
El return code 5 significa Connection Refused, not authorized (conexión rechazada, no autorizado). El broker exige autenticación o sus reglas de acceso bloquean al usuario. Envía un usuario y una contraseña válidos y revisa la ACL del broker o el ajuste allow_anonymous.