# Errors

When the gateway refuses or ends something, MQTT v5 clients get a reason code and AMQP clients get an error condition. The reason string or description names the subject, topic, key or property involved. The gateway logs the same text.

| Failure                                                                                                        | MQTT v5                                                                                             | AMQP                                                                         | Fix                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| NATS refuses the client's credential                                                                           | CONNACK `0x87 Not authorized`                                                                       | Close with `amqp:unauthorized-access` after the `open`                       | Fix the credential. Check the NATS user exists.                                                                       |
| NATS revokes the credential of a connected client                                                              | DISCONNECT `0x87 Not authorized`                                                                    | Close with `amqp:unauthorized-access`                                        | Fix the credential. Check the NATS user exists.                                                                       |
| No gateway user is in the client's NATS account                                                                | CONNACK `0x87 Not authorized`                                                                       | Close with `amqp:unauthorized-access` after the `open`                       | Add an `accounts` entry with the credential of a gateway user in that account.                                        |
| The client's NATS user cannot ask `$SYS.REQ.USER.INFO` for its account, or cannot receive the reply            | CONNACK `0x87 Not authorized`                                                                       | Close with `amqp:unauthorized-access` after the `open`                       | Let the user publish to `$SYS.REQ.USER.INFO` and subscribe to its inbox.                                              |
| The gateway cannot serve the client's account now                                                              | CONNACK `0x88 Server unavailable`                                                                   | Close with `amqp:internal-error` after the `open`                            | Run `mq-gateway check`. Fix what it names. See the causes below.                                                      |
| The NATS user cannot publish to the subject                                                                    | `0x87 Not authorized` on the acknowledgement                                                        | `rejected` with `amqp:unauthorized-access`                                   | Give the NATS user publish permission on the subject.                                                                 |
| The NATS user cannot subscribe, or cannot create the consumer                                                  | SUBACK `0x87 Not authorized`                                                                        | Attach refused with `amqp:unauthorized-access`                               | Give the NATS user the subscribe and JetStream API permissions.                                                       |
| The subject is one of the gateway's own (`$MQG.>`)                                                             | `0x87 Not authorized`. A will there gets CONNACK `0x87`                                             | `rejected` or attach refused with `amqp:unauthorized-access`                 | Use a different subject.                                                                                              |
| The filter is under another client's reply prefix (`$MQG/reply/`)                                              | SUBACK `0x87 Not authorized`                                                                        |                                                                              | Subscribe only under the prefix the client's own connection got.                                                      |
| The filter is under `_INBOX/`                                                                                  | SUBACK `0x87 Not authorized`                                                                        |                                                                              | Use the reply prefix from Response Information.                                                                       |
| No binding stores the subject of a QoS 1 or 2 or unsettled send                                                | `0x83 Implementation specific error` on the acknowledgement                                         | `rejected` with `amqp:not-allowed`                                           | Add a binding for the subject. Or send at QoS 0, or presettled.                                                       |
| No binding stores the topic of a QoS 1 or 2 will                                                               | CONNACK `0x9B QoS not supported`                                                                    |                                                                              | Add a binding for the will topic. Or set the will QoS to 0.                                                           |
| With a sessions bucket, the client's NATS user cannot publish to its will topic                                | CONNACK `0x87 Not authorized`                                                                       |                                                                              | Give the NATS user publish permission on the will topic.                                                              |
| A route cannot place the message: a property that the template names is missing, or differs from the subject   | `0x83 Implementation specific error`. A will gets CONNACK `0x83`. The gateway drops a QoS 0 message | `rejected` with `amqp:invalid-field`. The gateway drops a presettled message | Send the property that the route template names.                                                                      |
| The receiver's selector does not parse                                                                         |                                                                                                     | Attach refused with `amqp:invalid-field`                                     | Fix the selector at the position that the description gives. See [Selectors](/mq-gateway/0.4/reference/selectors.md). |
| The gateway cannot serve the receiver's selector                                                               |                                                                                                     | Attach refused with `amqp:not-implemented`                                   | Change the selector. See the causes below.                                                                            |
| The stream does not store the message within 5s                                                                | DISCONNECT `0x83 Implementation specific error`, with no acknowledgement                            | `rejected` with `amqp:internal-error`                                        | Check that the stream has a leader and free space. The MQTT client sends the message again when it reconnects.        |
| The stream is at its consumer limit: each MQTT session with a QoS 1 or 2 subscription holds one consumer on it | SUBACK `0x97 Quota exceeded`                                                                        | Attach refused with `amqp:resource-limit-exceeded`                           | Set `max_consumers` on the stream above the number of sessions. Or delete unused consumers.                           |
| An operator or JetStream deletes the consumer of a subscription                                                | DISCONNECT `0x80 Unspecified error`                                                                 | Detach with `amqp:resource-deleted`                                          | Connect again and subscribe again. For AMQP, attach the link again.                                                   |
| The message is larger than the NATS server's `max_payload`                                                     | DISCONNECT `0x95 Packet too large`                                                                  | `amqp:link:message-size-exceeded`                                            | Send a smaller message, or increase `max_payload`.                                                                    |
| Another client connects with the same client ID                                                                | DISCONNECT `0x8E Session taken over`                                                                |                                                                              | Give each client a unique client ID.                                                                                  |
| The client sends nothing for 1.5 times its keep-alive, or for 60s on AMQP                                      | DISCONNECT `0x8D Keep Alive timeout`                                                                | Close with `amqp:resource-limit-exceeded`                                    | Send a ping within the keep-alive or idle time-out.                                                                   |
| The client reads too slowly                                                                                    | The gateway closes the connection without a packet                                                  | The gateway closes the connection without a frame                            | Read faster, or subscribe to fewer messages.                                                                          |
| An operator kicks the client                                                                                   | DISCONNECT `0x98 Administrative action`                                                             | Close with `amqp:connection:forced`                                          | Connect again.                                                                                                        |
| The gateway stops, or closes the connection in lame duck mode                                                  | DISCONNECT `0x8B Server shutting down`, or `0x9C Use another server` with `mqtt.server-reference`   | Close with `amqp:connection:forced`                                          | Connect again. The client connects to another gateway.                                                                |
| The client connects while the gateway stops                                                                    | CONNACK `0x88 Server unavailable`, or `0x9C Use another server` with `mqtt.server-reference`        | Close with `amqp:connection:forced`                                          | Connect to another gateway.                                                                                           |
| The client's NATS connection closes and does not reconnect                                                     | DISCONNECT `0x80 Unspecified error`                                                                 | Close with `amqp:connection:forced`                                          | Connect again.                                                                                                        |

To give a NATS user the permissions in the Fix column, see [Configure listeners and auth](/mq-gateway/0.4/how-to/configure-listeners-and-auth.md).

A stream that sets no `max_consumers` gets the server default. On nats-server 2.15 and later, the default is 1,000 consumers per stream. `mq-gateway check` warns when a bound stream has this limit or less.

AMQP uses `amqp:connection:forced` for the last four rows. The description tells them apart: `disconnected by administrator`, `gateway stopping` or `NATS connection closed`.

## Server unavailable

The gateway refuses a connection with `0x88 Server unavailable`, or closes it with `amqp:internal-error` after the `open`, when:

* The gateway cannot reach NATS.
* The client's account failed the start-up check, for example because a stream or bucket is missing. The gateway serves the account when the check passes again, with no restart.
* The gateway could not find the account of one of its own gateway users. That user needs permission for `$SYS.REQ.USER.INFO`.
* Another gateway took over the MQTT client ID in the last second.
* The gateway is stopping.

## Selectors the gateway cannot serve

The gateway refuses a receiver's link with `amqp:not-implemented` when:

* The link has more than one selector. Send one.
* The selector reads `JMSXDeliveryCount`. Delete that term.
* The address is on a work-queue stream, and the subject does not answer the whole selector. Use only `=` and `IN` on properties that a route puts in the subject, with 64 value combinations or fewer.
* A route serves the address, and the selector's `=` and `IN` terms on the route's properties allow no value. An example is `region = 'EU' AND region = 'US'` on `orders.{region}`.

## MQTT 3.1.1

MQTT 3.1.1 has codes only in CONNACK and SUBACK. The gateway refuses a 3.1.1 CONNECT with return code `0x05 Not authorized` or `0x03 Server unavailable`, and a subscription with SUBACK `0x80`. A will that the gateway cannot store gets `0x05`. For every other failure in the table, the gateway closes the connection without a packet.
