# Reason Codes (/connectors/mqtt/reference/reason-codes) This reference lists every MQTT reason code the KubeMQ MQTT connector produces, the packet type it appears on, and the exact conditions that trigger it. **These are MQTT 5.0 reason codes.** MQTT 3.1.1 does not carry reason codes on PUBACK or SUBACK (the fields do not exist). For MQTT 3.1.1 connections the connector either drops the message silently or closes the connection without a reason code — see [MQTT 3.1.1 behavior](#mqtt-311-behavior). ## Full reason code table [#full-reason-code-table] | Code | Hex | Packet(s) | Meaning | Triggering conditions | | ------------------------------------ | ------ | ----------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Success | `0x00` | PUBACK, SUBACK, CONNACK | Operation succeeded | Normal success. Also returned when a retained PUBLISH is **silently dropped** — the PUBACK still succeeds even though the message was discarded (see the [retain gotcha](#the-retain-silent-drop-gotcha-code-0x00)). | | Granted QoS 1 | `0x01` | SUBACK | Subscription granted at QoS 1 | The normal success code for any QoS-1 subscribe (Events, Events-Store, or `$share` Queues). Also the granted code when a QoS-2 subscribe is downgraded to QoS 1 — e.g. a `$share//queues/` subscription requested at QoS 2. | | Unspecified error | `0x80` | PUBACK, SUBACK | Broker not ready or internal error | (1) The broker is starting up or shutting down: all incoming publishes and subscribes are rejected with this code until the broker signals ready. (2) The internal message bus returned an error for a publish routed to Events, Events-Store, or Queues. No reason string is included in the PUBACK (information boundary — clients receive the code only; the actual error is in audit + logs). | | Implementation-specific error | `0x83` | SUBACK, PUBACK | Valid request, not supported by this connector | **SUBACK** — subscription rejected for a policy reason: (a) `$share/` on a non-queues topic; (b) plain `queues/` subscribe without `$share`; (c) `$share//queues/` at QoS 0; (d) subscribe to `commands/` or `queries/` (MQTT clients cannot be RPC responders); (e) subscribe to another client's `$reply//...` namespace. **PUBACK** — RPC publish rejected: (f) `ResponseTopic` is missing; (g) `ResponseTopic` is outside the publisher's own `$reply//...` namespace. | | Bad user name or password | `0x86` | CONNACK | Authentication failure | (a) Auth is enabled and the CONNECT `Password` field is empty. (b) Auth is enabled and the JWT in `Password` is invalid or expired. The `Username` field is not used for authentication (display-only). | | Not authorized | `0x87` | PUBACK, SUBACK | ACL denied the publish or subscribe | The authorization policy denied access to the resolved (pattern, channel) for this client. **PUBACK** — write (publish) was denied. **SUBACK** — read (subscribe) was denied. The resolved channel and pattern are checked but not included in the ack (information boundary). | | Server shutting down | `0x8B` | DISCONNECT | Graceful server shutdown | The KubeMQ node is stopping. The connector sends DISCONNECT `0x8B` to all connected clients before closing. Clients should reconnect to another node or retry. | | Topic filter invalid | `0x8F` | SUBACK | Topic filter is structurally malformed | (a) Any segment of the topic filter is empty (leading `/`, trailing `/`, or double `/`). (b) `DefaultPattern=none` and the filter has no recognized prefix. (c) Empty `$share` group: `$share//queues/`. | | Topic name invalid | `0x90` | PUBACK | Topic name is structurally malformed or unmappable | (a) Any segment of the topic is empty. (b) `DefaultPattern=none` and the topic has no recognized prefix. (c) The topic resolves to an empty KubeMQ channel. | | Quota exceeded | `0x97` | PUBACK | Server-side quota exhausted | (a) The in-flight RPC pending map is full: `RpcMaxPending` (default `1024`) concurrent outstanding RPC requests already exist. (b) The PUBLISH carries more than **32** MQTT 5.0 user properties, or the total byte length of all user-property key + value pairs exceeds **4096 bytes**. | | Retain not supported | `0x9A` | CONNACK | Retain is disabled; Will-retain requested | The CONNECT packet includes `Will-retain=true`. The connector rejects the connection before the session is established. A retained PUBLISH **at runtime** does **not** produce this code — it is silently dropped with a success PUBACK `0x00` (see `0x00` above). | | Wildcard subscriptions not supported | `0xA2` | SUBACK | Wildcard used on an unsupported pattern | A subscription filter contains `+` or `#` but the resolved pattern is **not** Events. Wildcards are allowed only on Events (`events/`) subscriptions. `queues/+/foo`, `store/#`, `commands/+/svc`, etc. trigger this code. | ## Per-pattern quick reference [#per-pattern-quick-reference] ### Events (`events/`) [#events-eventsch] | Scenario | Code | | ------------------------------------- | -------------------------------------- | | Publish success | `0x00` | | Subscribe success | `0x00` / `0x01` / `0x02` (granted QoS) | | Wildcard subscribe (`+`, `#`) success | `0x00` / `0x01` | | Internal-bus error on publish | `0x80` | | Broker not ready | `0x80` | | ACL deny on publish | `0x87` (PUBACK) | | ACL deny on subscribe | `0x87` (SUBACK) | | Empty channel (`events/` only) | `0x90` (publish) / `0x8F` (subscribe) | ### Events-Store (`store/`) [#events-store-storech] Same as Events, except wildcard subscribes return `0xA2` (wildcards are not allowed on Events-Store). ### Queues (`queues/` produce / `$share//queues/` consume) [#queues-queuesch-produce--sharegqueuesch-consume] | Scenario | Code | | -------------------------------------------------------- | --------------- | | Produce (publish) success | `0x00` | | `$share//queues/` subscribe at QoS 1 | `0x01` | | `$share//queues/` subscribe at QoS 2 (downgraded) | `0x01` | | Plain `queues/` subscribe | `0x83` | | `$share//queues/` at QoS 0 | `0x83` | | `$share/` on a non-queues topic | `0x83` | | Internal-bus error on produce | `0x80` | | ACL deny on produce | `0x87` (PUBACK) | | ACL deny on `$share//queues/` subscribe | `0x87` (SUBACK) | ### Commands and Queries (RPC, MQTT 5.0 only) [#commands-and-queries-rpc-mqtt-50-only] | Scenario | Code | | ----------------------------------------------------- | ---------------------------------------- | | Valid MQTT 5.0 RPC publish (acknowledged immediately) | `0x00` (PUBACK sent before response) | | Subscribe to `commands/` or `queries/` | `0x83` (MQTT clients are not responders) | | MQTT 3.1.1 publish to `commands/` or `queries/` | `0x00` (silently dropped — no RPC) | | Missing `ResponseTopic` property | `0x83` | | `ResponseTopic` outside own `$reply//` | `0x83` | | `RpcMaxPending` exceeded | `0x97` | ### RPC timeout [#rpc-timeout] There is **no reason code** for an RPC timeout. The server audits `rpc.timeout` and discards the pending entry, but the PUBACK was already sent at `0x00` when the publish was received. The client must detect the missing response via its own timeout. ## The retain silent-drop gotcha (code `0x00`) [#the-retain-silent-drop-gotcha-code-0x00] `RetainAvailable=0` is advertised to connecting clients. If a client ignores this and sends a retained PUBLISH: 1. The retain flag is silently stripped. 2. The bridge detects the retain flag and drops the message without routing it. 3. The bridge audits `publish.error` with description `"retain not supported"`. 4. The **PUBACK is `0x00` (success)**. The sender has no wire-level indication that the message was dropped. This is the only case where `0x00` does not mean the message was delivered. The **only** retain-related error code is `0x9A`, and it fires only on CONNECT when the Will message has `retain=true`. ## MQTT 3.1.1 behavior [#mqtt-311-behavior] MQTT 3.1.1 does not support reason codes on PUBACK or SUBACK. The connector handles this as follows: | Situation | v5 code | v3.1.1 behavior | | ------------------------------- | -------------------- | -------------------------------------------- | | Publish success | `0x00` | Normal PUBACK (no reason code field) | | Broker not ready | `0x80` | Message silently dropped; no wire indication | | Internal-bus error | `0x80` | Message silently dropped | | Retain publish | `0x00` (silent drop) | Message silently dropped | | RPC publish to commands/queries | `0x00` (silent drop) | Message silently dropped | | User-prop cap exceeded | `0x97` | Message silently dropped | | Wildcard on non-events | `0xA2` | Subscription silently rejected | | Unsupported subscribe pattern | `0x83` | Subscription silently rejected | | `$share` queue at QoS 0 | `0x83` | Subscription silently rejected | All rejections for v3.1.1 connections are audited as `publish.error` or `subscription.error` in the server audit log. ## Reason codes in order [#reason-codes-in-order] | Hex | Decimal | Packet | Name | | ------ | ------- | ------------------------- | ------------------------------------ | | `0x00` | 0 | PUBACK / SUBACK / CONNACK | Success | | `0x01` | 1 | SUBACK | Granted QoS 1 | | `0x80` | 128 | PUBACK / SUBACK | Unspecified error | | `0x83` | 131 | PUBACK / SUBACK | Implementation-specific error | | `0x86` | 134 | CONNACK | Bad user name or password | | `0x87` | 135 | PUBACK / SUBACK | Not authorized | | `0x8B` | 139 | DISCONNECT | Server shutting down | | `0x8F` | 143 | SUBACK | Topic filter invalid | | `0x90` | 144 | PUBACK | Topic name invalid | | `0x97` | 151 | PUBACK | Quota exceeded | | `0x9A` | 154 | CONNACK | Retain not supported | | `0xA2` | 162 | SUBACK | Wildcard subscriptions not supported | ## Related [#related]