Skip to main content
Version: 0.4

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.

FailureMQTT v5AMQPFix
NATS refuses the client's credentialCONNACK 0x87 Not authorizedClose with amqp:unauthorized-access after the openFix the credential. Check the NATS user exists.
NATS revokes the credential of a connected clientDISCONNECT 0x87 Not authorizedClose with amqp:unauthorized-accessFix the credential. Check the NATS user exists.
No gateway user is in the client's NATS accountCONNACK 0x87 Not authorizedClose with amqp:unauthorized-access after the openAdd 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 replyCONNACK 0x87 Not authorizedClose with amqp:unauthorized-access after the openLet the user publish to $SYS.REQ.USER.INFO and subscribe to its inbox.
The gateway cannot serve the client's account nowCONNACK 0x88 Server unavailableClose with amqp:internal-error after the openRun mq-gateway check. Fix what it names. See the causes below.
The NATS user cannot publish to the subject0x87 Not authorized on the acknowledgementrejected with amqp:unauthorized-accessGive the NATS user publish permission on the subject.
The NATS user cannot subscribe, or cannot create the consumerSUBACK 0x87 Not authorizedAttach refused with amqp:unauthorized-accessGive 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 0x87rejected or attach refused with amqp:unauthorized-accessUse a different subject.
The filter is under another client's reply prefix ($MQG/reply/)SUBACK 0x87 Not authorizedSubscribe only under the prefix the client's own connection got.
The filter is under _INBOX/SUBACK 0x87 Not authorizedUse the reply prefix from Response Information.
No binding stores the subject of a QoS 1 or 2 or unsettled send0x83 Implementation specific error on the acknowledgementrejected with amqp:not-allowedAdd a binding for the subject. Or send at QoS 0, or presettled.
No binding stores the topic of a QoS 1 or 2 willCONNACK 0x9B QoS not supportedAdd 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 topicCONNACK 0x87 Not authorizedGive 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 subject0x83 Implementation specific error. A will gets CONNACK 0x83. The gateway drops a QoS 0 messagerejected with amqp:invalid-field. The gateway drops a presettled messageSend the property that the route template names.
The receiver's selector does not parseAttach refused with amqp:invalid-fieldFix the selector at the position that the description gives. See Selectors.
The gateway cannot serve the receiver's selectorAttach refused with amqp:not-implementedChange the selector. See the causes below.
The stream does not store the message within 5sDISCONNECT 0x83 Implementation specific error, with no acknowledgementrejected with amqp:internal-errorCheck 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 itSUBACK 0x97 Quota exceededAttach refused with amqp:resource-limit-exceededSet max_consumers on the stream above the number of sessions. Or delete unused consumers.
An operator or JetStream deletes the consumer of a subscriptionDISCONNECT 0x80 Unspecified errorDetach with amqp:resource-deletedConnect again and subscribe again. For AMQP, attach the link again.
The message is larger than the NATS server's max_payloadDISCONNECT 0x95 Packet too largeamqp:link:message-size-exceededSend a smaller message, or increase max_payload.
Another client connects with the same client IDDISCONNECT 0x8E Session taken overGive each client a unique client ID.
The client sends nothing for 1.5 times its keep-alive, or for 60s on AMQPDISCONNECT 0x8D Keep Alive timeoutClose with amqp:resource-limit-exceededSend a ping within the keep-alive or idle time-out.
The client reads too slowlyThe gateway closes the connection without a packetThe gateway closes the connection without a frameRead faster, or subscribe to fewer messages.
An operator kicks the clientDISCONNECT 0x98 Administrative actionClose with amqp:connection:forcedConnect again.
The gateway stops, or closes the connection in lame duck modeDISCONNECT 0x8B Server shutting down, or 0x9C Use another server with mqtt.server-referenceClose with amqp:connection:forcedConnect again. The client connects to another gateway.
The client connects while the gateway stopsCONNACK 0x88 Server unavailable, or 0x9C Use another server with mqtt.server-referenceClose with amqp:connection:forcedConnect to another gateway.
The client's NATS connection closes and does not reconnectDISCONNECT 0x80 Unspecified errorClose with amqp:connection:forcedConnect 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, 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.