RabbitMQ health check fails with RabbitMQ 4.1+ due to frameMax incompatibility

[mag123c]

Is there an existing issue for this?

• I have searched the existing issues

Current behavior

• RabbitMQ health check tests fail when using RabbitMQ 4.1.0 or higher
• Error message: "negotiated frame_max = 4096 is lower than the minimum allowed value (8192)"
• All CI/CD pipelines fail on RMQ-related tests, blocking PRs

Minimum reproduction code

1. git clone https://github.com/nestjs/terminus.git
2. docker compose up -d (Use the current docker-compose.yml which specifies rabbitmq:4-management-alpine)
3. pnpm i && pnpm build
4. pnpm test:e2e

Steps to reproduce

1. Start RabbitMQ 4.1+ container (as configured in docker-compose.yml)
2. Run e2e tests: npx jest --config=e2e/jest-e2e.json e2e/health-checks/microservice.health.e2e-spec.ts
3. RMQ health check test fails with frameMax negotiation error
4. Check docker logs: docker logs rabbitmq | grep frame_max

Expected behavior

• RabbitMQ health check should successfully connect to RabbitMQ 4.1+ instances
• Tests should pass without manual frameMax configuration
• The library should handle RabbitMQ version compatibility automatically

Package version

11.0.0

NestJS version

11.*

Node.js version

18.x, 20.x, 22.x

In which operating systems have you tested?

• macOS
• Windows
• Linux

Other

• Docker image: rabbitmq:4-management-alpine (currently 4.1.3)
• This affects all projects using @nestjs/terminus with RabbitMQ 4.1+
• Related amqplib issue: Negotiated frame_max = 4096 is lower than the minimum allowed value (8192) amqp-node/amqplib#791

[mag123c]

Root Cause Analysis

After investigation, I found that this is caused by a breaking change in RabbitMQ 4.1.0 (released April 2025):

• RabbitMQ 4.1.0 increased the minimum pre-authentication frame_max from 4096 to 8192 bytes to accommodate larger JWT tokens
• The current amqplib@0.10.5 dependency defaults to frame_max: 4096, which is now rejected by RabbitMQ 4.1+
• Official announcement: https://www.rabbitmq.com/blog/2025/04/15/rabbitmq-4.1.0-is-released

Proposed Solution

Update amqplib from 0.10.5 to 0.10.6 or higher:

"amqplib": "^0.10.6"

This version includes the fix for RabbitMQ 4.1+ compatibility by automatically negotiating a higher frame_max value.

Verification

Solution 1: Update amqplib

• With amqplib@0.10.5 - test fails
• With amqplib@0.10.6 - test passes

Solution 2: Add frameMax to test configuration

microservice.pingCheck<RmqOptions>('rmq', {
  transport: Transport.RMQ,
  options: {
    urls: ['amqp://localhost:5672?frameMax=65536'], // Set frameMax above 8192
  },
})

• This also makes the test pass
• However, this requires updating all RMQ health checks in user code

Impact

This issue affects:

• All current PRs failing CI tests
• Any production deployments using RabbitMQ 4.1+ with @nestjs/terminus
• Docker setups using rabbitmq:4-management-alpine tag (auto-updates to 4.1.3)

[injae-kim]

Fix PR: #2673 👍