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	SASL outcome auth	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	SASL outcome auth	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	SASL outcome auth	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	SASL outcome sys-temp	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 an admin subject ($MQGW.admin.>)	0x87 Not authorized. A will there gets CONNACK 0x87	rejected or attach refused with amqp:unauthorized-access	Use a different subject.
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 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.

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, server shutting down or NATS connection closed.

Server unavailable

The gateway refuses a connection with 0x88 Server unavailable, or SASL sys-temp, 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.

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.