{"record":{"id":"fa718f74818031db","repo":"pinpoint-apm/pinpoint","slug":"maxbuckets-should-be-in-1-256-range","errorCode":null,"errorMessage":"maxBuckets should be in 1..256 range","messagePattern":"maxBuckets should be in 1\\.\\.256 range","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"commons-hbase/src/main/java/com/navercorp/pinpoint/common/hbase/wd/OneByteSimpleHash.java","lineNumber":37,"sourceCode":"import com.navercorp.pinpoint.common.util.BytesUtils;\nimport com.navercorp.pinpoint.common.util.MathUtils;\n\n/**\n * Copy from sematext/HBaseWD\n */\npublic class OneByteSimpleHash implements ByteHasher {\n    private static final SaltKey SALT_KEY = ByteSaltKey.SALT;\n\n    private final int mod;\n    private final SaltKeyPrefix saltKeyPrefix;\n    /**\n     * Creates a new instance of this class.\n     *\n     * @param maxBuckets max buckets number, should be in 1...255 range\n     */\n    public OneByteSimpleHash(int maxBuckets) {\n        if (maxBuckets < 1 || maxBuckets > 256) {\n            throw new IllegalArgumentException(\"maxBuckets should be in 1..256 range\");\n        }\n        // i.e. \"real\" maxBuckets value = maxBuckets or maxBuckets-1\n        this.mod = maxBuckets;\n        this.saltKeyPrefix = new ModSaltKeyPrefix(mod);\n    }\n\n\n\n    @Override\n    public byte getHashPrefix(byte[] originalKey) {\n        return getHashPrefix(originalKey, 0);\n    }\n\n    @Override\n    public byte getHashPrefix(byte[] originalKey, int saltKeySize) {\n        int hash = MathUtils.fastAbs(BytesUtils.hashBytes(originalKey, saltKeySize, originalKey.length));\n        return (byte) (hash % mod);\n    }","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/commons-hbase/src/main/java/com/navercorp/pinpoint/common/hbase/wd/OneByteSimpleHash.java#L19-L55","documentation":"OneByteSimpleHash buckets rows into at most 256 values (one byte of salt). The constructor validates maxBuckets is within 1..256, throwing IllegalArgumentException otherwise, since values outside that range cannot be encoded in a single byte key prefix.","triggerScenarios":"Constructing new OneByteSimpleHash(maxBuckets) with maxBuckets < 1 or > 256, typically from a configurable 'number of buckets' property for HBase table row distribution (salted tables).","commonSituations":"Setting hbase table bucket count to 512 or 1024 assuming more buckets improve distribution; misparsed config yielding 0; confusing this class with a two-byte hasher that supports larger ranges.","solutions":["Set maxBuckets between 1 and 256 inclusive; typical pinpoint tables use 32, 64, or 128 buckets","If you need more than 256 buckets, use a different Hasher implementation (e.g. two-byte hashing) if available","Fix the configuration source that produced an out-of-range bucket count"],"exampleFix":"// before\nHasher hasher = new OneByteSimpleHash(512);\n// after\nHasher hasher = new OneByteSimpleHash(256);","handlingStrategy":"validation","validationCode":"if (buckets < 1 || buckets > 256) {\n    throw new IllegalArgumentException(\"buckets must be in 1..256, got \" + buckets);\n}\nHasher h = new OneByteSimpleHash(buckets);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Clamp/validate the bucket-count config property at startup","Use standard bucket counts (32/64/128/256) for salted pinpoint tables","Choose a different Hasher implementation when >256 buckets are genuinely needed"],"tags":["hbase","hashing","argument-validation","configuration"],"backgroundTag":"argument-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"}