MQRC 2030: Message too large for the queue

What it means

Each queue has a MAXMSGL attribute, and so does the queue manager. A message put without segmentation can't be longer than the smaller of the two. If it is, the put fails with MQCC_FAILED and reason 2030, and nothing is written to the queue.

On distributed MQ, an application can set MQMF_SEGMENTATION_ALLOWED in the MsgFlags field of the MQMD. The queue manager then splits a long message into segments that fit. Segmentation can still fail if the segments would be too small to hold the data, so 2030 is still possible with the flag set. IBM MQ for z/OS doesn't support segmentation. It accepts the flag and ignores it, so on z/OS the message must fit the limits as it is.

The code also turns up on channels. When a message channel agent can't put an arriving message on the target queue because it is too long, the reason goes into the Feedback field of a report message, or into the dead-letter header if the message goes to the dead-letter queue.

Common causes

• The application sends a larger payload than the queue was sized for, such as a file, an image or a batch of records in one message. The default MAXMSGL on a new queue is 4 MB.
• The local queue allows the size, but the target queue on the remote queue manager has a lower MAXMSGL. The receiving channel then reports 2030 and sends the message to its dead-letter queue.
• The queue's MAXMSGL was raised but the queue manager's MAXMSGL was not. The smaller limit still applies, so the put can fail with 2030 or with 2031.
• The program passes a wrong BufferLength, larger than the real data, so MQ sees a much longer message than intended.
• On z/OS, the queue is a shared queue in a coupling facility structure that can't hold the message size. Shared queue messages over about 63 KB need a structure at CFLEVEL(4) or later with offload to SMDS or Db2.

How to find the problem

1. Check the limits on both objects with DISPLAY QLOCAL(PAYMENTS.OUT) MAXMSGL and DISPLAY QMGR MAXMSGL in runmqsc. On z/OS use the same commands with the command prefix.
2. Log the message length the program passes on MQPUT. Compare it with both limits and with what the program meant to send.
3. If the failure is on a channel, look at the dead-letter queue on the receiving side. The MQDLH header holds reason 2030 and the original destination. Browse it with amqsbcg or dmpmqmsg on distributed MQ.
4. For a shared queue on z/OS, display the queue's CFSTRUCT and then DISPLAY CFSTRUCT(...) to check CFLEVEL and OFFLOAD.

How to fix it

• Check BufferLength first. If it is wrong, fix the program and nothing else needs to change.
• If large messages are expected, raise the queue's MAXMSGL with ALTER QLOCAL(...) MAXMSGL(n). Raise the queue manager's MAXMSGL and every channel's MAXMSGL along the route too, on both ends. The highest value is 100 MB.
• Split the data into several smaller messages, ideally in a message group so the receiver can put them back together.
• On distributed MQ only, set MQMF_SEGMENTATION_ALLOWED so the queue manager can segment the message.
• For a message on a dead-letter queue, fix the limit and then replay it with the dead-letter handler (runmqdlq on distributed, CSQUDLQH on z/OS).

Technical reviewer: Albert Joseph, WND Software.

Last reviewed 2026-10-18 by the WND Software team. Written in our own words. For the full reference, check IBM’s MQ documentation for your version.