I've been reading data-service release notes for the places where a server upgrade breaks a client nobody touched. RabbitMQ 4.1 has a clean example, and it mostly hits Node.js services.

What changed

AMQP 0-9-1 clients and the broker agree on a maximum frame size when a connection opens. Before authentication finishes, RabbitMQ uses a smaller, fixed size. In 4.1.0 that initial size went from 4096 to 8192 bytes. The release notes give the reason: larger JWT tokens need to fit.

The side effect is a new floor. A client that asks for a frame_max below 8192 can't connect to 4.1.0 or later. The broker drops the connection, and in Node the app sees ECONNRESET.

The release notes name amqplib, a popular Node.js client that used a default of 4096. They say to move to 0.10.7 or later. amqplib's own changelog puts the fix one release earlier, in 0.10.6: "Use a frame_max of 131072 by default for RabbitMQ 4.1.0 compatibility." Either way, anything older asks for 4096 unless you told it otherwise.

Today's server defaults, from the RabbitMQ limits page, are frame_max 131072 and initial_frame_max 8192.

Why this one gets missed

The note is there, in the 4.1.0 release notes. A few things still get in the way.

The people who read broker release notes are the people upgrading the broker. The amqplib version lives in a lockfile inside a service image, owned by another team, maybe built a year ago.

The upgrade path also lets you skip the notes. RabbitMQ supports going from 3.13.x straight to 4.2.x. If you do that, you'll read the 4.2 notes carefully. The frame_max change is in 4.1's.

And amqplib is often not a direct dependency. Wrapper libraries pin their own copy, so your package.json can say nothing about amqplib while an old one sits in node_modules.

How to check, read-only

Start with which brokers you run and at what version:

kubectl get pods -A -o json | jq -r '.items[] | .metadata.namespace as $ns | .spec.containers[] | select(.image | test("(^|/)rabbitmq(:|@|$)")) | $ns + "\t" + .image' | sort -u 

Then ask the broker what its current clients negotiated. This is the useful one, because it works on the 3.13 or 4.0 broker you run today:

kubectl exec -n <namespace> <rabbitmq-pod> -- rabbitmqctl -q list_connections name user frame_max 

frame_max is a documented column, the maximum frame size in bytes for that connection. To show only the ones under the new floor:

kubectl exec -n <namespace> <rabbitmq-pod> -- rabbitmqctl -q list_connections name user frame_max | awk -F'\t' '$3 > 0 && $3 < 8192' 

Each line is a connection that 4.1 will refuse. The user column usually tells you which service it is.

That only covers clients connected right now. A nightly job or a consumer scaled to zero won't show up. For those, look in the image. If you have an SBOM tool like syft:

syft <image> -o json | jq -r '.artifacts[] | select(.name == "amqplib") | .version + "\t" + (.locations[0].path // "")' 

The path matters. It shows whether the old copy is yours or one nested under another library. In a repo, npm ls amqplib --all gives the same picture.

What to do about it

If amqplib is your direct dependency, bump it. 0.10.7 or later satisfies both the RabbitMQ notes and the amqplib changelog.

If a library pins an old amqplib, add an npm overrides entry so the whole tree gets a fixed version:

{ "overrides": { "amqplib": "^0.10.7" } } 

If you can't change versions yet, pass a frameMax of 8192 or more when you connect. The RabbitMQ notes recommend leaving the 131072 default alone and not overriding it, so treat this as a stopgap.

Other Node and Ruby clients have their own floor for the same change: @cloudamqp/amqp-client needs 3.2.1, rabbitmq-client needs 5.0.3, rabbot needs 4.0.0, and the Ruby amqp-client gem needs 0.2.0.

One more check before a 3.13 to 4.x rolling upgrade, since you'll have the shell open anyway. RabbitMQ's upgrade guide says all stable feature flags have to be enabled first, or the upgrade may fail:

kubectl exec -n <namespace> <rabbitmq-pod> -- rabbitmqctl -q list_feature_flags name state 

I'd run the list_connections check a week before the upgrade and again that morning. The list changes every time someone deploys.