{"record":{"id":"16184e232e031c55","repo":"apache/pulsar","slug":"ranges-must-be-0-65535-but-provided-range-is","errorCode":null,"errorMessage":"Ranges must be [0, 65535] but provided range is ","messagePattern":"Ranges must be \\[0, 65535\\] but provided range is ","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/ReaderBuilderImpl.java","lineNumber":241,"sourceCode":"    public ReaderBuilder<T> subscriptionName(String subscriptionName) {\n        conf.setSubscriptionName(subscriptionName);\n        return this;\n    }\n\n    @Override\n    public ReaderBuilder<T> readCompacted(boolean readCompacted) {\n        conf.setReadCompacted(readCompacted);\n        return this;\n    }\n\n    @Override\n    public ReaderBuilder<T> keyHashRange(Range... ranges) {\n        checkArgument(ranges != null && ranges.length > 0,\n                \"Cannot specify a null ofr an empty key hash ranges for a reader\");\n        for (int i = 0; i < ranges.length; i++) {\n            Range range1 = ranges[i];\n            if (range1.getStart() < 0 || range1.getEnd() > DEFAULT_HASH_RANGE_SIZE) {\n                throw new IllegalArgumentException(\"Ranges must be [0, 65535] but provided range is \" + range1);\n            }\n            for (int j = 0; j < ranges.length; j++) {\n                Range range2 = ranges[j];\n                if (i != j && range1.intersect(range2) != null) {\n                    throw new IllegalArgumentException(\"Key hash ranges with overlap between \" + range1\n                            + \" and \" + range2);\n                }\n            }\n        }\n        conf.setKeyHashRanges(Arrays.asList(ranges));\n        return this;\n    }\n\n    @Override\n    public ReaderBuilder<T> poolMessages(boolean poolMessages) {\n        conf.setPoolMessages(poolMessages);\n        return this;\n    }","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/ReaderBuilderImpl.java#L223-L259","documentation":"ReaderBuilder.keyHashRange() restricts each key-hash Range to fit within the non-negative space of the default hash range (0..65535, DEFAULT_HASH_RANGE_SIZE). Passing a range that starts below 0 or ends above 65535 throws this IllegalArgumentException because keys would never hash into such a range.","triggerScenarios":"Calling keyHashRange(Range.of(start, end)) where start < 0 or end > 65535, e.g. Range.of(0, 131071) or Range.of(-10, 100). Note the thrown message omits the interpolated range value.","commonSituations":"Computing ranges from a different hash-size assumption (e.g. full 32-bit hash space instead of the 65536-slot range), splitting a larger interval evenly and rounding past 65535, or typos when defining ranges for a non-overlapping reader subscription.","solutions":["Clamp all ranges so start >= 0 and end <= 65535","Compute ranges as fractions of DEFAULT_HASH_RANGE_SIZE (65536 slots, inclusive end 65535) rather than the raw hash width","Check each Range endpoint before calling keyHashRange"],"exampleFix":"// before\nreaderBuilder.keyHashRange(Range.of(0, 100000));\n// after\nreaderBuilder.keyHashRange(Range.of(0, 65535));","handlingStrategy":"validation","validationCode":"for (Range r : ranges) {\n    if (r.getStart() < 0 || r.getEnd() > 65535) {\n        throw new IllegalArgumentException(\"Range out of [0,65535]: \" + r);\n    }\n}","typeGuard":"boolean isValidHashRange(Range r) {\n    return r != null && r.getStart() >= 0 && r.getEnd() <= 65535;\n}","tryCatchPattern":"try {\n    readerBuilder.keyHashRange(ranges);\n} catch (IllegalArgumentException e) {\n    log.error(\"Invalid key hash range: {}\", e.getMessage());\n    throw new ConfigurationException(\"keyHashRange endpoints must be within [0, 65535]\", e);\n}","preventionTips":["Derive ranges from the 65536-slot default hash size, never from raw hash bit width","Clamp and validate endpoints before building the ranges","Add a startup-time config validation for all key hash ranges"],"tags":["java","pulsar-client","range-validation","illegal-argument"],"backgroundTag":"range-out-of-bounds","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"}