MQRC 2031: Message too large for the queue manager

What it means

MQPUT or MQPUT1 could not place the message because its length exceeded an applicable maximum. The queue-manager limit is one part of the path; the queue and channels can impose smaller limits. IBM also documents restrictions when MQ message segmentation is requested.

Check the number of bytes actually supplied, including relevant message headers. A character count or compressed file size in an application log may not describe the buffer passed to MQ.

A troubleshooting example

An order export grows from 2 MB to 6 MB. The destination queue allows 10 MB, but the queue manager still permits 4 MB. The producer sees 2031 and operators initially inspect only the queue. Build a path worksheet containing the queue-manager, queue and channel maxima, then test a payload just below and just above the agreed limit. Include any headers added by middleware. This makes the boundary explicit and prevents another component from becoming the next bottleneck.

Common causes

• A larger payload crosses the queue-manager maximum even though the target queue allows it.
• An intermediate channel permits a smaller maximum than either endpoint.
• The application supplies an incorrect BufferLength or assumes segmentation can split every format.

How to find the problem

1. Record BufferLength at the failing call and compare successful and failing payload sizes. Confirm the units are bytes.
2. Inspect MAXMSGL for the queue manager, destination queue and channels on the route. Preserve the values before changing them.
3. Determine whether the error is returned to the producer or appears in a report message after a remote delivery attempt.
4. Check MsgFlags and the message format if segmentation is part of the design. Verify that consumers support the intended message handling.

How to fix it

• Correct a mistaken length first. Do not increase infrastructure limits to accommodate a buffer-size calculation bug.
• If the business message legitimately needs more space, agree compatible limits across the complete path and test its largest expected form.
• Consider application-level splitting or supported MQ segmentation only with a defined reconstruction and failure-recovery design. Bound retries for an unchanged oversized message.

What it looks like

Illustrative diagnostic notes; not an IBM message template.
MQPUT BufferLength: 6291456 bytes
Queue MAXMSGL: 10485760
Queue-manager MAXMSGL: 4194304
Reason=2031: queue capacity alone is not enough.

Technical reviewer: Albert Joseph, WND Software.

Updated 2026-10-23. IBM documentation checked for this article. Written in our own words. For the full reference, check IBM’s MQ documentation for your version.