pinpoint-apm/pinpoint · error · IllegalArgumentException

maxBuckets should be in 1..256 range

Error message

maxBuckets should be in 1..256 range

What it means

RangeOneByteSimpleHash hashes one byte of the row key to select one of maxBuckets buckets, so the bucket count must fit in one byte: 1..256. The constructor throws IllegalArgumentException when maxBuckets is outside that range.

Source

Thrown at commons-hbase/src/main/java/com/navercorp/pinpoint/common/hbase/wd/RangeOneByteSimpleHash.java:40

/**
 * Copy from sematext/HBaseWD
 * Provides handy methods to distribute
 *
 * @author Alex Baranau
 * @author emeroad
 */
public class RangeOneByteSimpleHash implements ByteHasher {
    private static final SaltKey SALT_KEY = ByteSaltKey.SALT;

    protected final int start;
    protected final int end;
    private final int mod;

    private final SaltKeyPrefix saltKeyPrefix;

    public RangeOneByteSimpleHash(int start, int end, int maxBuckets) {
        if (maxBuckets < 1 || maxBuckets > 256) {
            throw new IllegalArgumentException("maxBuckets should be in 1..256 range");
        }

        this.start = start;
        this.end = end;
        // i.e. "real" maxBuckets value = maxBuckets or maxBuckets-1
        this.mod = maxBuckets;

        this.saltKeyPrefix = new ModSaltKeyPrefix(mod);
    }


    @Override
    public byte getHashPrefix(byte[] originalKey) {
        return getHashPrefix(originalKey, 0);
    }

    @Override
    public byte getHashPrefix(byte[] originalKey, int saltKeySize) {

View on GitHub (pinned to 744c3d3075)

Solutions

1. Use a maxBuckets value between 1 and 256 (commonly 32, 64, or 256).
2. Validate the value at config-load time before instantiating the hasher.
3. If more than 256 buckets are needed, switch to a hasher designed for it rather than inflating this one.

Example fix

// before
Hasher hasher = new RangeOneByteSimpleHash(0, 2, 1000);
// after
Hasher hasher = new RangeOneByteSimpleHash(0, 2, 256);

if (maxBuckets < 1 || maxBuckets > 256) {
    throw new IllegalArgumentException("maxBuckets must be in 1..256, got: " + maxBuckets);
}
Hasher hasher = new RangeOneByteSimpleHash(start, end, maxBuckets);

try {
    hasher = new RangeOneByteSimpleHash(start, end, maxBuckets);
} catch (IllegalArgumentException e) {
    log.error("maxBuckets {} out of 1..256", maxBuckets, e);
    hasher = new RangeOneByteSimpleHash(start, end, 256);
}

When it happens

Trigger: Calling new RangeOneByteSimpleHash(start, end, maxBuckets) with maxBuckets < 1 or maxBuckets > 256.

Common situations: Hand-written hashing config in Pinpoint's hbase client setup; typo such as 1024 buckets; reading bucket count from an environment-specific config that was edited incorrectly.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• maxBuckets should be in 1..256 range
• maxBuckets should be in 1..256 range
• Unknown AgentType:
• Failed to detect pinpoint profile. Please add -Dpinpoint.act
• unsupported profile or profile alias:

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/916fd84d5ed767f6. Report an issue: GitHub.