pinpoint-apm/pinpoint · error · IllegalArgumentException

maxBuckets should be in 1..256 range

Error message

maxBuckets should be in 1..256 range

What it means

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.

Source

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

import com.navercorp.pinpoint.common.util.BytesUtils;
import com.navercorp.pinpoint.common.util.MathUtils;

/**
 * Copy from sematext/HBaseWD
 */
public class OneByteSimpleHash implements ByteHasher {
    private static final SaltKey SALT_KEY = ByteSaltKey.SALT;

    private final int mod;
    private final SaltKeyPrefix saltKeyPrefix;
    /**
     * Creates a new instance of this class.
     *
     * @param maxBuckets max buckets number, should be in 1...255 range
     */
    public OneByteSimpleHash(int maxBuckets) {
        if (maxBuckets < 1 || maxBuckets > 256) {
            throw new IllegalArgumentException("maxBuckets should be in 1..256 range");
        }
        // 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) {
        int hash = MathUtils.fastAbs(BytesUtils.hashBytes(originalKey, saltKeySize, originalKey.length));
        return (byte) (hash % mod);
    }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Set maxBuckets between 1 and 256 inclusive; typical pinpoint tables use 32, 64, or 128 buckets
2. If you need more than 256 buckets, use a different Hasher implementation (e.g. two-byte hashing) if available
3. Fix the configuration source that produced an out-of-range bucket count

Example fix

// before
Hasher hasher = new OneByteSimpleHash(512);
// after
Hasher hasher = new OneByteSimpleHash(256);

if (buckets < 1 || buckets > 256) {
    throw new IllegalArgumentException("buckets must be in 1..256, got " + buckets);
}
Hasher h = new OneByteSimpleHash(buckets);

When it happens

Trigger: Constructing new OneByteSimpleHash(maxBuckets) with maxBuckets < 1 or > 256, typically from a configurable 'number of buckets' property for HBase table row distribution (salted tables).

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

Related errors

• maxBuckets should be in 1..256 range
• maxBuckets should be in 1..256 range
• Invalid namespace : <namespace>
• HBase version compatibility violation HBaseClient:%s, HBaseS
• negative tieOffset:<tieOffset>

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