RabbitMQ 常见错误代码

概述

本文档整理了 RabbitMQ 常见的错误代码、错误信息和解决方案，帮助开发者快速定位和解决问题。

连接错误

CONNECTION_REFUSED

属性	内容
错误码	CONNECTION_REFUSED
说明	连接被拒绝
厸见原因	RabbitMQ 服务未启动、端口错误、防火墙阻止

解决方案:

# 检查服务状态
rabbitmqctl status

# 检查端口
netstat -tlnp | grep 5672

# 检查防火墙
sudo ufw status
sudo firewall-cmd --list-ports

ACCESS_REFUSED

属性	内容
错误码	ACCESS_REFUSED
说明	访问被拒绝
常见原因	用户名密码错误、用户不存在、权限不足

解决方案:

# 检查用户
rabbitmqctl list_users

# 重置密码
rabbitmqctl change_password guest new_password

# 检查权限
rabbitmqctl list_user_permissions guest

CONNECTION_FORCED

属性	内容
错误码	CONNECTION_FORCED
说明	连接被强制关闭
常见原因	管理员手动关闭、资源告警触发

解决方案:

# 检查告警状态
rabbitmq-diagnostics check_alarms

# 检查内存使用
rabbitmq-diagnostics memory_breakdown

# 检查磁盘空间
df -h

通道错误

CHANNEL_ERROR

属性	内容
错误码	CHANNEL_ERROR
说明	通道错误
常见原因	通道已关闭、协议错误

解决方案:

# Python 示例：正确处理通道错误
import pika

try:
    channel.basic_publish(...)
except pika.exceptions.ChannelClosedByBroker as e:
    print(f"Channel closed: {e}")
    channel = connection.channel()

NOT_FOUND

属性	内容
错误码	404 NOT_FOUND
说明	资源不存在
常见原因	队列不存在、交换机不存在

解决方案:

# 检查队列是否存在
rabbitmqctl list_queues name

# 检查交换机是否存在
rabbitmqctl list_exchanges name

RESOURCE_LOCKED

属性	内容
错误码	RESOURCE_LOCKED
说明	资源被锁定
常见原因	独占队列被其他连接占用

解决方案:

# 查看队列连接
rabbitmqctl list_queues name exclusive consumer_channel

# 关闭占用连接
rabbitmqctl close_connection <connection_pid> "Release exclusive queue"

资源错误

PRECONDITION_FAILED

属性	内容
错误码	PRECONDITION_FAILED
说明	前置条件失败
常见原因	队列/交换机参数不匹配、重复声明参数不一致

错误信息示例:

PRECONDITION_FAILED - inequivalent arg 'durable' for queue 'my_queue':
received 'false' but current is 'true'

解决方案:

# 删除现有队列重新创建
rabbitmqctl delete_queue my_queue

# 或修改声明参数与现有队列一致

RESOURCE_ERROR

属性	内容
错误码	RESOURCE_ERROR
说明	资源错误
常见原因	内存不足、磁盘空间不足

解决方案:

# 检查内存告警
rabbitmqctl status | grep memory

# 调整内存限制
# rabbitmq.conf
vm_memory_high_watermark.relative = 0.6

# 检查磁盘空间
df -h

# 调整磁盘限制
disk_free_limit.absolute = 10GB

NOT_ALLOWED

属性	内容
错误码	NOT_ALLOWED
说明	操作不允许
常见原因	用户权限不足、虚拟主机限制

解决方案:

# 检查用户权限
rabbitmqctl list_user_permissions <username>

# 设置权限
rabbitmqctl set_permissions -p / <username> ".*" ".*" ".*"

消息错误

NO_ROUTE

属性	内容
错误码	NO_ROUTE
说明	消息无法路由
常见原因	没有匹配的绑定、路由键错误

解决方案:

# 检查绑定
rabbitmqctl list_bindings source_name destination_name routing_key

# 检查交换机类型
rabbitmqctl list_exchanges name type

NO_CONSUMERS

属性	内容
错误码	NO_CONSUMERS
说明	没有消费者
常见原因	队列没有活跃消费者

解决方案:

# 检查消费者
rabbitmqctl list_queues name consumers

# 启动消费者
# 或配置死信队列处理

MESSAGE_TOO_LARGE

属性	内容
错误码	MESSAGE_TOO_LARGE
说明	消息过大
常见原因	消息体超过 frame_max 限制

解决方案:

# 调整 frame_max 配置
# rabbitmq.conf
frame_max = 131072  # 默认 128KB

# 或拆分大消息

集群错误

NODE_NOT_FOUND

属性	内容
错误码	NODE_NOT_FOUND
说明	节点未找到
常见原因	节点未启动、节点名称错误、网络不通

解决方案:

# 检查节点状态
rabbitmqctl cluster_status

# 检查 Erlang Cookie
cat /var/lib/rabbitmq/.erlang.cookie

# 检查网络连通性
ping node2.example.com

CLUSTER_NAME_MISMATCH

属性	内容
错误码	CLUSTER_NAME_MISMATCH
说明	集群名称不匹配
常见原因	节点加入错误的集群

解决方案:

# 重置节点
rabbitmqctl stop_app
rabbitmqctl reset
rabbitmqctl join_cluster rabbit@node1
rabbitmqctl start_app

PARTITION

属性	内容
错误码	PARTITION
说明	网络分区
常见原因	网络故障、节点间通信中断

解决方案:

# 检查分区状态
rabbitmqctl cluster_status | grep partitions

# 处理分区（选择一种策略）
# 1. 自动处理（配置）
# cluster_partition_handling = autoheal

# 2. 手动处理
rabbitmqctl stop_app
rabbitmqctl start_app

插件错误

PLUGIN_NOT_ENABLED

属性	内容
错误码	PLUGIN_NOT_ENABLED
说明	插件未启用
常见原因	需要的插件未安装或未启用

解决方案:

# 查看插件状态
rabbitmq-plugins list

# 启用插件
rabbitmq-plugins enable rabbitmq_management

PLUGIN_ERROR

属性	内容
错误码	PLUGIN_ERROR
说明	插件错误
常见原因	插件版本不兼容、插件配置错误

解决方案:

# 禁用问题插件
rabbitmq-plugins disable <plugin_name>

# 检查插件版本兼容性
rabbitmq-plugins list | grep <plugin_name>

认证错误

AUTHENTICATION_FAILED

属性	内容
错误码	AUTHENTICATION_FAILED
说明	认证失败
常见原因	用户名密码错误、认证后端配置错误

解决方案:

# 检查用户
rabbitmqctl list_users

# 重置密码
rabbitmqctl change_password <username> <new_password>

# 检查认证后端配置
rabbitmqctl environment | grep auth_backends

CERTIFICATE_ERROR

属性	内容
错误码	CERTIFICATE_ERROR
说明	证书错误
常见原因	证书过期、证书链不完整、证书格式错误

解决方案:

# 检查证书
openssl x509 -in /path/to/cert.pem -text -noout

# 检查证书过期
openssl x509 -in /path/to/cert.pem -checkend 0

# 验证证书链
openssl verify -CAfile /path/to/ca.pem /path/to/cert.pem

常见错误信息速查表

错误信息	原因	解决方案
connection refused	服务未启动	启动 RabbitMQ 服务
access refused	认证失败	检查用户名密码
queue not found	队列不存在	先声明队列
exchange not found	交换机不存在	先声明交换机
no route	无法路由消息	检查绑定关系
precondition failed	参数不匹配	删除重建或修改参数
resource locked	资源被锁定	检查独占资源
memory alarm	内存告警	增加内存或调整限制
disk alarm	磁盘告警	清理磁盘或调整限制
channel error	通道错误	重新创建通道
frame too large	帧过大	调整 frame_max
internal error	内部错误	查看日志排查

错误排查流程

1. 连接问题排查

# 步骤 1: 检查服务状态
rabbitmqctl status

# 步骤 2: 检查端口
netstat -tlnp | grep 5672

# 步骤 3: 检查日志
tail -f /var/log/rabbitmq/rabbit@hostname.log

# 步骤 4: 检查防火墙
sudo ufw status

2. 认证问题排查

# 步骤 1: 检查用户列表
rabbitmqctl list_users

# 步骤 2: 检查用户权限
rabbitmqctl list_user_permissions <username>

# 步骤 3: 检查虚拟主机
rabbitmqctl list_vhosts

# 步骤 4: 测试连接
rabbitmqctl authenticate_user <username> <password>

3. 资源问题排查

# 步骤 1: 检查告警
rabbitmq-diagnostics check_alarms

# 步骤 2: 检查内存
rabbitmq-diagnostics memory_breakdown

# 步骤 3: 检查磁盘
df -h

# 步骤 4: 检查连接数
rabbitmqctl list_connections

注意事项

1. 日志查看: 遇到错误首先查看日志文件
2. 版本兼容: 注意客户端和服务端版本兼容性
3. 权限检查: 确保用户有足够的权限
4. 资源监控: 定期监控内存、磁盘等资源

相关链接

• 配置参考
• 命令速查表
• HTTP API 参考