Unacknowledged messages accumulate while workers stall

Understand the likely causes

• A handler may wait indefinitely on a dependency, queue deliveries in an unbounded local executor, lose completion-to-ack handoff or misuse channel-scoped tags. The configured per-consumer window can multiply across consumers.

Capture which deliveries remain owned

Record vhost, queue, queue type, consumer count, prefetch and the aligned ready/unacked trend. Correlate the same operation identities with handler start, external request and completion evidence. Low ready does not mean work finished; messages can simply be held by consumers. Distinguish a legitimate long operation from an unbounded wait and from a handler that never started after local dispatch. Preserve the first channel error and connection lifecycle evidence before restarting anything. A heartbeat proves a transport relationship under its rules, not that the business handler or an external provider is healthy.

Count the window at its actual scope

Under a declared per-consumer interpretation, two consumers with prefetch twenty can together hold forty unacknowledged deliveries. That is a delivery-count exposure, not forty worker threads and not a complete memory estimate. Include decoded object sizes, local queues and pending external requests. A larger prefetch cannot make a blocked dependency complete faster and can increase replay cost after failure. The local arithmetic checks a supplied full-window condition without reading broker state. Confirm the selected client and queue-type semantics before using a global application cap that was actually configured per consumer.

consumers = 2
prefetch_each = 20
observed_unacked = 40
declared_window = consumers * prefetch_each
assert observed_unacked == declared_window
print(declared_window)

40

Inspect the effect-to-ack handoff

If effects finish but unacked does not fall, inspect the completion callback and the client-supported thread handoff. Acknowledgments must use the original channel context, and multiple acknowledgments must not cover unfinished deliveries. Unknown-delivery-tag errors can close a channel and create requeue churn that looks like repeated processing failure. If effects have not finished, bound dependency waits and define terminal handling rather than acknowledging early. A delivery acknowledgment timeout can close the channel under its policy; it does not automatically cancel a remote action already issued. Keep uncertain destination effects available for reconciliation.

Restore bounded progress without skipping responsibility

Choose a targeted correction for the observed cause: bounded remote waits, a limited local executor, correct channel ownership or a reviewed prefetch window. Preserve original identity when interrupted deliveries return. Do not force-ack unfinished work or purge queues to make unacked disappear. This guide changes no QoS setting and starts or stops no worker. Real acceptance after an authorized repair should show a bounded synthetic delivery completing its effect and then acknowledgment, followed by a crash/restart case that produces one accepted business result despite possible redelivery.

Keep it from recurring

• Document per-consumer limits, processing concurrency and acknowledgment ownership together. Use finite external deadlines, preserve exact channel/attempt context in diagnostics and monitor business completion alongside transport liveness.