pinpoint-apm/pinpoint · error · IllegalArgumentException

maxBuckets should be in 1..256 range

Error message

maxBuckets should be in 1..256 range

What it means

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.

Source

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

    private final SaltKeyPrefix[] saltKeyPrefixes;

    private final SecondaryHashFunction secondaryHashFunction;

    public static ByteHasher ofRandom(int start, int end, int maxBuckets, int secondaryMod) {
        SecondaryHashFunction secondaryHashFunction = new SecondaryRandomHashFunction(secondaryMod);
        return new RangeDoubleHash(start, end, maxBuckets, secondaryMod, secondaryHashFunction);
    }

    public static ByteHasher ofSecondary(int start, int end, int maxBuckets, int secondaryMod, int secondaryStart, int secondaryEnd) {
        SecondaryHashFunction secondaryHashFunction = new SecondaryRangeHashFunction(secondaryStart, secondaryEnd, secondaryMod);
        return new RangeDoubleHash(start, end, maxBuckets, secondaryMod, secondaryHashFunction);
    }


    public RangeDoubleHash(int start, int end, int maxBuckets, int secondaryMod, SecondaryHashFunction secondaryHashFunction) {
        if (maxBuckets < 1 || maxBuckets > MAX_BUCKETS) {
            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.maxBuckets = maxBuckets;

        this.saltKeyPrefixes = newSaltKeyPrefixes(maxBuckets);
        this.secondaryMod = secondaryMod;

        this.secondaryHashFunction = Objects.requireNonNull(secondaryHashFunction, "secondaryFunction");
    }

    private SaltKeyPrefix[] newSaltKeyPrefixes(int maxBuckets) {
        final SaltKeyPrefix[] saltKeyPrefixes = new SaltKeyPrefix[maxBuckets];
        for (int i = 0; i < saltKeyPrefixes.length; i++) {
            saltKeyPrefixes[i] = new DoubleHashKeyPrefix(i);
        }
        return saltKeyPrefixes;

View on GitHub (pinned to 744c3d3075)

Solutions

1. Set maxBuckets to a value in 1..256, typically 32 or 256 depending on the number of region servers.
2. Validate the configured bucket count before constructing RangeDoubleHash and fail fast at startup with a clear message.
3. If the value comes from a config file, check that it was not accidentally set to 0, negative, or a byte-scaled value.

Example fix

// before
Hasher hasher = new RangeDoubleHash(0, 4, 512, 256, secondaryFn);
// after
Hasher hasher = new RangeDoubleHash(0, 4, 256, 256, secondaryFn);

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

try {
    hasher = new RangeDoubleHash(start, end, maxBuckets, secondaryMod, fn);
} catch (IllegalArgumentException e) {
    log.error("Invalid maxBuckets config: {}", maxBuckets, e);
    throw new ConfigurationException(e);
}

When it happens

Trigger: 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.

Common situations: 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).

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/d7b137dd8cdbb015. Report an issue: GitHub.