apache/pulsar · error · RuntimeException

The update payload operation only support multi chunked mess

Error message

The update payload operation only support multi chunked messages.

What it means

RawMessageImpl.updatePayloadForChunkedMessage reassembles a chunked message by replacing its payload with a merged buffer, but it only works when the message metadata actually records chunk counts (hasNumChunksFromMsg with numChunksFromMsg > 1). For non-chunked or single-chunk messages there is nothing to reassemble, so it throws RuntimeException.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/api/raw/RawMessageImpl.java:88

            long ledgerId, long entryId, long batchIndex) {
        RawMessageImpl msg = RECYCLER.get();
        msg.msgMetadata = msgMetadata;
        msg.msgMetadata.retain();

        if (singleMessageMetadata != null) {
            msg.singleMessageMetadata.copyFrom(singleMessageMetadata);
            msg.setSingleMessageMetadata = true;
        }
        msg.messageId.ledgerId = ledgerId;
        msg.messageId.entryId = entryId;
        msg.messageId.batchIndex = batchIndex;
        msg.payload = payload;
        return msg;
    }

    public RawMessage updatePayloadForChunkedMessage(ByteBuf chunkedTotalPayload) {
        if (!msgMetadata.getMetadata().hasNumChunksFromMsg() || msgMetadata.getMetadata().getNumChunksFromMsg() <= 1) {
            throw new RuntimeException("The update payload operation only support multi chunked messages.");
        }
        payload = chunkedTotalPayload;
        return this;
    }

    @Override
    public Map<String, String> getProperties() {
        if (setSingleMessageMetadata && singleMessageMetadata.getPropertiesCount() > 0) {
            return singleMessageMetadata.getPropertiesList().stream()
                      .collect(Collectors.toMap(KeyValue::getKey, KeyValue::getValue,
                              (oldValue, newValue) -> newValue));
        } else if (msgMetadata.getMetadata().getPropertiesCount() > 0) {
            return msgMetadata.getMetadata().getPropertiesList().stream()
                    .collect(Collectors.toMap(KeyValue::getKey, KeyValue::getValue,
                            (oldValue, newValue) -> newValue));
        } else {
            return Collections.emptyMap();
        }

View on GitHub (pinned to 820761864e)

Solutions

1. Check metadata before merging: only call updatePayloadForChunkedMessage when hasNumChunksFromMsg() && getNumChunksFromMsg() > 1; otherwise keep the original payload.
2. Enable message chunking on the producer (setChunkingEnabled / maxMessageSize config) so chunk metadata is present.
3. Catch RuntimeException and fall back to using the unmodified RawMessage payload for non-chunked messages.

Example fix

// before
msg.updatePayloadForChunkedMessage(totalBuffer);
// after
if (msg.getMetadata().getMetadata().hasNumChunksFromMsg()
        && msg.getMetadata().getMetadata().getNumChunksFromMsg() > 1) {
    msg.updatePayloadForChunkedMessage(totalBuffer);
} else {
    // use msg as-is: not a multi-chunk message
}

boolean isMultiChunk = rawMsg.getMetadata().getMetadata().hasNumChunksFromMsg()
    && rawMsg.getMetadata().getMetadata().getNumChunksFromMsg() > 1;

if (isMultiChunk) {
    msg.updatePayloadForChunkedMessage(totalBuffer);
} // else: use the message payload as-is

When it happens

Trigger: Calling updatePayloadForChunkedMessage on a RawMessage whose metadata lacks numChunksFromMsg or has numChunksFromMsg <= 1 — i.e. the message was not published with chunking enabled or arrived as a single chunk.

Common situations: Raw reading consumers that process topics mixing chunked and non-chunked messages; chunking disabled on the producer but the consumer code unconditionally calls the merge path; messages produced by old brokers/clients that don't set numChunksFromMsg metadata.

Related errors

• Cannot delete the global namespace ${nsName}. There are stil
• Cannot delete the global namespace ${namespaceName}. There a
• chunkSize must be > 0 when chunking is enabled
• Cannot parse encrypted message + msgMetadata + on topic +
• Keys and values must be >= 0

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/3635504f13f040e4. Report an issue: GitHub.