apache/druid · error · ISE

bucketSize must be a power of two but was[%,d]

Error message

bucketSize must be a power of two but was[%,d]

What it means

The FrontCoded string encoding strategy requires its bucketSize to be a power of two (FrontCodedIndexed constraint for efficient bucket indexing). The constructor throws this ISE when a configured bucketSize has more than one bit set, e.g. 3, 12, 100.

Solutions

1. Set bucketSize to a power of two (2, 4, 8, 16, 32, ...) — FrontCodedIndexed.DEFAULT_BUCKET_SIZE is 16 if omitted
2. Validate user-supplied bucketSize values before writing them into the column format spec
3. Remove the bucketSize property entirely to fall back to the default valid value

Example fix

// before
"stringDictionaryEncoding": { "type": "front-coded", "bucketSize": 10 } // ISE: not a power of two
// after
"stringDictionaryEncoding": { "type": "front-coded", "bucketSize": 16 } // 16 = 2^4

if (bucketSize != null && Integer.bitCount(bucketSize) != 1) {
  throw new IllegalArgumentException("bucketSize must be a power of two, got " + bucketSize);
}

boolean isValidBucketSize(Integer bucketSize) {
  return bucketSize == null || (bucketSize > 0 && Integer.bitCount(bucketSize) == 1);
}

try {
  FrontCoded fc = new FrontCoded("front-coded", bucketSize, version);
} catch (ISE e) {
  LOG.warn(e, "Invalid bucketSize, using default");
  fc = new FrontCoded("front-coded", null, version); // defaults to 16
}

When it happens

Trigger: Deserializing or constructing a FrontCoded StringEncodingStrategy with @JsonProperty bucketSize set to a non-power-of-two integer (e.g. 3, 6, 24) from a column format spec / segment metadata JSON.

Common situations: Hand-edited ingestion/compaction specs choosing an arbitrary bucket size like 10; copying a spec where someone changed bucketSize from 16 to 20; a custom config generator that doesn't validate the constraint.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• bucketSize must be a power of two (from 1 up to 128) but…
• Detected conflicting prefixes in join clauses
• Detected duplicate prefix in join clauses
• maxStringBytes must be greater than 0
• maxStringBytes must be greater than 0

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/f19c5b9aec0fad04. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/column/StringEncodingStrategy.java:105

  class FrontCoded implements StringEncodingStrategy
  {

    @JsonProperty
    private final int bucketSize;

    @JsonProperty
    private final byte formatVersion;

    @JsonCreator
    public FrontCoded(
        @JsonProperty("bucketSize") @Nullable Integer bucketSize,
        @JsonProperty("formatVersion") @Nullable Byte version
    )
    {
      this.bucketSize = bucketSize == null ? FrontCodedIndexed.DEFAULT_BUCKET_SIZE : bucketSize;
      if (Integer.bitCount(this.bucketSize) != 1) {
        throw new ISE("bucketSize must be a power of two but was[%,d]", bucketSize);
      }
      this.formatVersion = version == null
                           ? FrontCodedIndexed.DEFAULT_VERSION
                           : FrontCodedIndexed.validateVersion(version);
    }

    public FrontCoded(@Nullable Integer bucketSize)
    {
      this(bucketSize, null);
    }

    @JsonProperty
    public int getBucketSize()
    {
      return bucketSize;
    }

    @JsonProperty

View on GitHub (pinned to 9b90983fd2)