Error & Reason Codes
The AMQP 0-9-1 channel and connection close codes (311–541) the KubeMQ RabbitMQ connector returns — their meanings, triggers, and channel-vs-connection scope.
The RabbitMQ (AMQP 0-9-1) connector returns standard AMQP 0-9-1 channel/connection close codes. This reference lists every code the connector emits, what triggers it, and whether it closes the offending channel or the whole connection. All codes are verified in the connector source.
Reason code table
| Code | Constant | Meaning | Trigger |
|---|---|---|---|
311 | replyContentTooLarge | content-too-large | body > MaxBodySize |
312 | replyNoRoute | no-route | mandatory=true unroutable → basic.return |
313 | replyNoConsumers | no-consumers | reserved — defined but not currently emitted in non-test source |
320 | replyConnectionForced | connection-forced | shutdown / conn-limit / graceful close |
402 | replyInvalidPath | invalid-path | bad / reserved vhost (incl. literal default) |
403 | replyAccessRefused | access-refused | auth fail / Read deny on consume / amq.* client declare / delete pre-declared / exclusive-consumer conflict |
404 | replyNotFound | not-found | passive declare of a missing exchange/queue |
405 | replyResourceLocked | resource-locked | exclusive-queue cross-connection access |
406 | replyPreconditionFailed | precondition-failed | redeclare mismatch, user-id mismatch, bad expiration, unknown delivery tag, reply-to no-ack rule, channel-length > 255 |
501 | replyFrameError | frame-error | bad frame-end, oversized frame |
502 | replySyntaxError | syntax-error | malformed method / field-table |
503 | replyCommandInvalid | command-invalid | unknown exchange type, out-of-state method, unsupported SASL mechanism (non-PLAIN) |
504 | replyChannelError | channel-error | data-plane / array failure |
505 | replyUnexpectedFrame | unexpected-frame | wire-level sequencing error |
530 | replyNotAllowed | not-allowed | duplicate consumer tag on a channel (RabbitMQ-dialect connection error) |
540 | replyNotImplemented | not-implemented | tx.*, exchange.bind/unbind, immediate=true, basic.recover-async, connection.update-secret |
541 | replyInternalError | internal-error | broker not ready (gated; new ops rejected until ready) |
313 replyNoConsumers is reserved. It is defined in the connector source but is not
currently emitted by non-test code. It is listed here for completeness only.
Channel vs connection errors
The scope of a close code tells you what gets torn down:
- Channel errors (e.g.
404,405,406,504) close the offending channel; the connection survives. - Connection errors (e.g.
320,403auth,501,502,503,505,530) close the whole connection.
Common triggers by scenario
| Scenario | Code |
|---|---|
Publish to a direct exchange with an unmatched key (no mandatory) | silent drop (no code) |
basic.publish(mandatory=true) unroutable | 312 |
expiration not ^\d+$ | 406 |
Consume amq.rabbitmq.reply-to with no-ack=false | 406 |
user-id ≠ Claims.ClientID (auth on) | 406 |
| Read deny on consume | 403 |
Bad / reserved (default) vhost; illegal vhost charset | 402 |
| Exclusive-queue cross-connection access | 405 |
| Redeclare with mismatched args; unknown delivery tag; channel name > 255 | 406 |
| Passive declare of a missing exchange/queue | 404 |
Client declares an amq.* exchange / deletes a pre-declared exchange | 403 |
Body > MaxBodySize | 311 / 406 |
| Bad frame-end / oversized frame / malformed method | 501 / 502 |
| Unsupported SASL mechanism (non-PLAIN) | 503 |
tx.* / exchange.bind/unbind / immediate=true / basic.recover-async | 540 |
| Connection limit reached | 320 |
| Broker not ready (gated) | 541 |
| Auth failure (bad JWT) | 403 + auth.failure audit |
Related
Capabilities
Supported methods, the not-implemented (540) set, inert arguments, and the nine gotchas.
Channel Mapping
The name charset and reserved-vhost rules behind the 402 / 406 codes.
Reliability
Handling 312 returns, DLX, and the publisher-confirm deviations in client code.
Authentication
The 403 / 406 / 503 codes behind SASL PLAIN and per-channel authorization.
Was this page helpful?
Connections & Observability
The RabbitMQ (AMQP 0-9-1) connector's observability surface — the connections and topology endpoints, Prometheus metrics, the SSE feed, and audit events.
Migrating from RabbitMQ
Point a RabbitMQ app at KubeMQ by changing only the AMQP 0-9-1 connection string — exchanges, DLX, confirms, and the connector deviations.