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 / token expiry (CONNECTION_FORCED - credential expired) |
402 | replyInvalidPath | invalid-path | bad / reserved vhost (incl. literal default); a vhost containing . |
403 | replyAccessRefused | access-refused | auth fail / Read deny on consume / Write deny on the exchange at publish / a connector-level permission denial (<verb> access to … refused for user …) / amq.* client declare / delete pre-declared / exclusive-consumer conflict (on any node) |
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, tx/confirm mode mix, transaction too large, x-max-length without x-overflow (or drop-head), x-delivery-limit refusals, x-message-ttl over the ceiling, queue.delete if-empty refusals |
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, a SASL mechanism that is not offered (ANONYMOUS, or EXTERNAL when certificate login is off) |
504 | replyChannelError | channel-error | frame on an unopened channel |
505 | replyUnexpectedFrame | unexpected-frame | wire-level sequencing error |
530 | replyNotAllowed | not-allowed | duplicate consumer tag on a channel; connection.update-secret refused (Secret update failed / New secret was refused by one of the backends); vhost access refused for a user with permission entries |
540 | replyNotImplemented | not-implemented | basic.recover-async(requeue=false), basic.qos(prefetch-size != 0), immediate=true, channel.flow(active=false) |
541 | replyInternalError | internal-error | broker not ready (gated; new ops rejected until ready); a destination-queue authorization refusal on a non-confirm publish |
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 |
SASL mechanism not offered (ANONYMOUS; EXTERNAL without certificate login) | 503 |
basic.recover-async(requeue=false) / basic.qos(prefetch-size != 0) / immediate=true / channel.flow(active=false) | 540 |
Publish denied on the exchange (platform Write, or connector write permission) | 403 |
connection.update-secret refused | 530 |
| Connection limit reached; token expired on an established connection | 320 |
| Broker not ready (gated) | 541 |
| Auth failure (bad JWT) | 403 + auth.failure audit |
Related
Capabilities
Supported methods, the not-implemented (540) set, enforced and inert arguments, and the 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 / 320 / 503 / 530 codes behind SASL login, token expiry and refresh, and 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.
Management HTTP API
The RabbitMQ-compatible management HTTP subset on port 15672 — endpoints, authentication, tags, visibility, and definitions export/import.