Nest.js中Bull任务无法执行，请求重试次数超限问题

报错信息 #

ERROR [ExceptionsHandler] Reached the max retries per request limit (which is 20). Refer to "maxRetriesPerRequest" option for details.

控制器打印队列客户端状态为reconnecting，说明Bull无法正常连接到Redis服务，导致请求重试耗尽。以下是具体排查和解决步骤：

1. 确认Redis服务是否正常运行 #

先排除最基础的服务可用性问题：

• 执行命令 redis-cli ping，返回PONG说明Redis正常运行；若报错，先启动Redis服务：
  • Windows：运行redis-server.exe启动服务端
  • Linux/macOS：执行systemctl start redis（或对应系统的启动命令）
• 检查Redis监听端口：执行redis-cli CONFIG GET port，确认返回值为6379

2. 补全Redis连接配置 #

如果Redis设置了密码或绑定了非localhost地址，需补充对应配置项：

// AppModule中的BullModule配置调整
BullModule.forRootAsync({
  useFactory: () => ({
    redis: {
      host: 'localhost',
      port: 6379,
      password: 'your-redis-password', // Redis设密码时必须添加
      // 若Redis绑定了特定IP，host改为对应地址，比如'192.168.1.100'
    },
    prefix: 'bull-queue',
    maxRetriesPerRequest: 3,
    defaultJobOptions: {
      attempts: 3,
      removeOnComplete: false,
      backoff: {
        type: 'exponential',
        delay: 1000,
      },
    },
  }),
}),

3. 确保maxRetriesPerRequest配置生效 #

将maxRetriesPerRequest直接放到Redis配置项中，确保传递到底层ioredis客户端：

redis: {
  host: 'localhost',
  port: 6379,
  maxRetriesPerRequest: 3, // 移至redis配置内
},

4. 单独测试Redis连接 #

在代码中用ioredis直接测试连接，排除Bull模块的问题：

// 临时添加到控制器或服务中测试
import Redis from 'ioredis';

const testRedis = new Redis({
  host: 'localhost',
  port: 6379,
});

testRedis.on('connect', () => console.log('Redis连接成功'));
testRedis.on('error', (err) => console.error('Redis连接失败:', err));

若测试连接失败，问题出在Redis本身或网络，而非Bull配置。

5. 排查网络与防火墙限制 #

• 确认本地防火墙未阻止6379端口的进出请求
• 若Redis部署在Docker中，检查端口映射是否正确（需添加-p 6379:6379参数）

6. 检查版本兼容性 #

确保依赖版本匹配：

• 查看package.json，@nestjs/bull需与bull版本兼容，建议使用官方推荐的版本组合
• 避免使用过于陈旧或未稳定的测试版本

内容的提问来源于stack exchange，提问作者Graham Morby