{"record":{"id":"d7b137dd8cdbb015","repo":"pinpoint-apm/pinpoint","slug":"maxbuckets-should-be-in-1-256-range-d7b137","errorCode":null,"errorMessage":"maxBuckets should be in 1..256 range","messagePattern":"maxBuckets should be in 1\\.\\.256 range","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"commons-hbase/src/main/java/com/navercorp/pinpoint/common/hbase/wd/RangeDoubleHash.java","lineNumber":61,"sourceCode":"\n    private final SaltKeyPrefix[] saltKeyPrefixes;\n\n    private final SecondaryHashFunction secondaryHashFunction;\n\n    public static ByteHasher ofRandom(int start, int end, int maxBuckets, int secondaryMod) {\n        SecondaryHashFunction secondaryHashFunction = new SecondaryRandomHashFunction(secondaryMod);\n        return new RangeDoubleHash(start, end, maxBuckets, secondaryMod, secondaryHashFunction);\n    }\n\n    public static ByteHasher ofSecondary(int start, int end, int maxBuckets, int secondaryMod, int secondaryStart, int secondaryEnd) {\n        SecondaryHashFunction secondaryHashFunction = new SecondaryRangeHashFunction(secondaryStart, secondaryEnd, secondaryMod);\n        return new RangeDoubleHash(start, end, maxBuckets, secondaryMod, secondaryHashFunction);\n    }\n\n\n    public RangeDoubleHash(int start, int end, int maxBuckets, int secondaryMod, SecondaryHashFunction secondaryHashFunction) {\n        if (maxBuckets < 1 || maxBuckets > MAX_BUCKETS) {\n            throw new IllegalArgumentException(\"maxBuckets should be in 1..256 range\");\n        }\n        this.start = start;\n        this.end = end;\n        // i.e. \"real\" maxBuckets value = maxBuckets or maxBuckets-1\n        this.maxBuckets = maxBuckets;\n\n        this.saltKeyPrefixes = newSaltKeyPrefixes(maxBuckets);\n        this.secondaryMod = secondaryMod;\n\n        this.secondaryHashFunction = Objects.requireNonNull(secondaryHashFunction, \"secondaryFunction\");\n    }\n\n    private SaltKeyPrefix[] newSaltKeyPrefixes(int maxBuckets) {\n        final SaltKeyPrefix[] saltKeyPrefixes = new SaltKeyPrefix[maxBuckets];\n        for (int i = 0; i < saltKeyPrefixes.length; i++) {\n            saltKeyPrefixes[i] = new DoubleHashKeyPrefix(i);\n        }\n        return saltKeyPrefixes;","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/commons-hbase/src/main/java/com/navercorp/pinpoint/common/hbase/wd/RangeDoubleHash.java#L43-L79","documentation":"RangeDoubleHash is a hash distribution strategy for the HBase write-distributor, and it enforces that the number of buckets used to spread writes across region servers stays between 1 and MAX_BUCKETS (256). The constructor throws IllegalArgumentException immediately when maxBuckets is below 1 or above 256, because a bucket count outside that range cannot partition salt keys correctly.","triggerScenarios":"Calling new RangeDoubleHash(start, end, maxBuckets, secondaryMod, secondaryHashFunction) (or the public factory that delegates to it) with maxBuckets < 1 or maxBuckets > 256, e.g. passing 0, a negative value, or 512.","commonSituations":"Configuration loaded from properties where the bucket count is user-supplied or mis-typed; copying a config from another Pinpoint deployment with a different table size; off-by-one or unit confusion (percent vs count).","solutions":["Set maxBuckets to a value in 1..256, typically 32 or 256 depending on the number of region servers.","Validate the configured bucket count before constructing RangeDoubleHash and fail fast at startup with a clear message.","If the value comes from a config file, check that it was not accidentally set to 0, negative, or a byte-scaled value."],"exampleFix":"// before\nHasher hasher = new RangeDoubleHash(0, 4, 512, 256, secondaryFn);\n// after\nHasher hasher = new RangeDoubleHash(0, 4, 256, 256, secondaryFn);","handlingStrategy":"validation","validationCode":"if (maxBuckets < 1 || maxBuckets > 256) {\n    throw new IllegalArgumentException(\"maxBuckets must be in 1..256, got: \" + maxBuckets);\n}\nHasher hasher = new RangeDoubleHash(start, end, maxBuckets, secondaryMod, fn);","typeGuard":null,"tryCatchPattern":"try {\n    hasher = new RangeDoubleHash(start, end, maxBuckets, secondaryMod, fn);\n} catch (IllegalArgumentException e) {\n    log.error(\"Invalid maxBuckets config: {}\", maxBuckets, e);\n    throw new ConfigurationException(e);\n}","preventionTips":["Validate bucket count against 1..256 at config load time.","Keep maxBuckets in the config alongside the region-server count and document the bound.","Write a startup smoke test that constructs all configured hashers."],"tags":["java","configuration","hbase","argument-validation"],"backgroundTag":"value-out-of-range","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}