When chunking is enabled, the producer splits a payload larger than the\n * configured chunk size into smaller pieces that are reassembled by the consumer.\n *\n *
Use {@link #ofDisabled()} to opt out, or {@link #builder()} to enable with a\n * specific chunk size.\n */\n@EqualsAndHashCode\n@ToString\npublic final class ChunkingPolicy {\n\n private static final ChunkingPolicy DISABLED = new ChunkingPolicy(false, 0);\n\n private final boolean enabled;\n private final int chunkSize;\n\n private ChunkingPolicy(boolean enabled, int chunkSize) {\n if (enabled && chunkSize <= 0) {\n throw new IllegalArgumentException(\"chunkSize must be > 0 when chunking is enabled\");\n }\n this.enabled = enabled;\n this.chunkSize = chunkSize;\n }\n\n /**\n * @return whether chunking is enabled\n */\n public boolean enabled() {\n return enabled;\n }\n\n /**\n * @return the maximum size of each chunk in bytes (only meaningful when {@link #enabled()})\n */\n public int chunkSize() {\n return chunkSize;\n }","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-api-v5/src/main/java/org/apache/pulsar/client/api/v5/config/ChunkingPolicy.java#L26-L62","documentation":"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.","triggerScenarios":"Calling ChunkingPolicy.builder().enabled(true).chunkSize(0) or .chunkSize(-4096); or enabling chunking while leaving chunkSize at a zero/negative value loaded from config.","commonSituations":"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.","solutions":["Set chunkSize to a positive byte count, e.g. ChunkingPolicy.builder().enabled(true).chunkSize(64 * 1024).","If you don't want chunking, leave enabled(false) and omit chunkSize.","Guard config loading: only apply chunkSize when it is > 0 and chunking is on."],"exampleFix":"// before\nChunkingPolicy cp = ChunkingPolicy.builder()\n .enabled(true)\n .chunkSize(0) // IllegalArgumentException\n .build();\n\n// after\nChunkingPolicy cp = ChunkingPolicy.builder()\n .enabled(true)\n .chunkSize(64 * 1024)\n .build();","handlingStrategy":"validation","validationCode":"boolean enabled = cfg.chunkingEnabled();\nint chunkSize = cfg.chunkSize();\nif (enabled && chunkSize <= 0) {\n throw new IllegalArgumentException(\"chunkSize must be > 0 when chunking is enabled\");\n}\nChunkingPolicy cp = ChunkingPolicy.builder().enabled(enabled).chunkSize(chunkSize).build();","typeGuard":"static boolean isValidChunking(boolean enabled, int chunkSize) { return !enabled || chunkSize > 0; }","tryCatchPattern":"try {\n cp = ChunkingPolicy.builder().enabled(true).chunkSize(size).build();\n} catch (IllegalArgumentException e) {\n log.warn(\"Invalid chunking config, disabling chunking\", e);\n cp = ChunkingPolicy.builder().enabled(false).build();\n}","preventionTips":["Only apply chunkSize from config when it is a positive number.","Don't use 0 as an 'unset' sentinel while chunking is enabled.","Treat chunkSize and chunkingEnabled as a coupled pair in your config schema."],"tags":["java","configuration","chunking","illegal-argument","producer"],"backgroundTag":"invalid-configuration-value","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}