apache/pulsar · error · IllegalArgumentException

chunkSize must be > 0 when chunking is enabled

Error message

chunkSize must be > 0 when chunking is enabled

What it means

ChunkingPolicy validates that when chunking is enabled, chunkSize must be strictly positive: it defines how many bytes each chunk of an oversized message is split into. Enabling chunking with chunkSize <= 0 would make splitting impossible or infinite, so the constructor throws IllegalArgumentException. Note that chunkSize is allowed to be any value (even 0 or negative) when chunking is disabled.

Source

Thrown at pulsar-client-api-v5/src/main/java/org/apache/pulsar/client/api/v5/config/ChunkingPolicy.java:44

 *
 * <p>When chunking is enabled, the producer splits a payload larger than the
 * configured chunk size into smaller pieces that are reassembled by the consumer.
 *
 * <p>Use {@link #ofDisabled()} to opt out, or {@link #builder()} to enable with a
 * specific chunk size.
 */
@EqualsAndHashCode
@ToString
public final class ChunkingPolicy {

    private static final ChunkingPolicy DISABLED = new ChunkingPolicy(false, 0);

    private final boolean enabled;
    private final int chunkSize;

    private ChunkingPolicy(boolean enabled, int chunkSize) {
        if (enabled && chunkSize <= 0) {
            throw new IllegalArgumentException("chunkSize must be > 0 when chunking is enabled");
        }
        this.enabled = enabled;
        this.chunkSize = chunkSize;
    }

    /**
     * @return whether chunking is enabled
     */
    public boolean enabled() {
        return enabled;
    }

    /**
     * @return the maximum size of each chunk in bytes (only meaningful when {@link #enabled()})
     */
    public int chunkSize() {
        return chunkSize;
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Set chunkSize to a positive byte count, e.g. ChunkingPolicy.builder().enabled(true).chunkSize(64 * 1024).
2. If you don't want chunking, leave enabled(false) and omit chunkSize.
3. Guard config loading: only apply chunkSize when it is > 0 and chunking is on.

Example fix

// before
ChunkingPolicy cp = ChunkingPolicy.builder()
    .enabled(true)
    .chunkSize(0) // IllegalArgumentException
    .build();

// after
ChunkingPolicy cp = ChunkingPolicy.builder()
    .enabled(true)
    .chunkSize(64 * 1024)
    .build();

boolean enabled = cfg.chunkingEnabled();
int chunkSize = cfg.chunkSize();
if (enabled && chunkSize <= 0) {
    throw new IllegalArgumentException("chunkSize must be > 0 when chunking is enabled");
}
ChunkingPolicy cp = ChunkingPolicy.builder().enabled(enabled).chunkSize(chunkSize).build();

static boolean isValidChunking(boolean enabled, int chunkSize) { return !enabled || chunkSize > 0; }

try {
    cp = ChunkingPolicy.builder().enabled(true).chunkSize(size).build();
} catch (IllegalArgumentException e) {
    log.warn("Invalid chunking config, disabling chunking", e);
    cp = ChunkingPolicy.builder().enabled(false).build();
}

When it happens

Trigger: Calling ChunkingPolicy.builder().enabled(true).chunkSize(0) or .chunkSize(-4096); or enabling chunking while leaving chunkSize at a zero/negative value loaded from config.

Common situations: Using 0 as an 'unset' sentinel for chunkSize while explicitly enabling chunking; a config file that sets chunkEnabled=true but chunkSize=0; copying a disabled-chunking template and flipping enabled to true without setting a size.

Understand the failure class

Background: "Invalid configuration value" and "Unsupported/Unknown setting value" errors: why libraries reject your config strings, numbers, and types — this error's family across 30 libraries.

Related errors

• maxMessages must be >= 0
• configuredService should not be an instance of SystemTopicBa
• The shared resource doesn't support thread pool configurati
• No resources have been configured while using shareConfigure
• jitterPercent must be in [0, 100]

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