apache/druid · error · org.apache.druid.java.util.common.IAE

Illegal number of buckets

Error message

Illegal number of buckets[%s], must be > 1

What it means

Constructor-time validation for the 'equalBuckets' post-aggregator: numBuckets must be greater than 1 because a single (or non-positive) bucket count cannot represent a meaningful equal-bucket histogram split. It fires at config-parse time when the numBuckets property is <= 1.

Solutions

1. Set numBuckets to an integer greater than 1 in the post-aggregator spec.
2. Verify the query JSON passes numBuckets explicitly rather than relying on a default of 0.

When it happens

Trigger: Thrown at extensions-core/histogram/src/main/java/org/apache/druid/query/aggregation/histogram/EqualBucketsPostAggregator.java:54 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at extensions-core/histogram/src/main/java/org/apache/druid/query/aggregation/histogram/EqualBucketsPostAggregator.java:54

import java.util.Objects;
import java.util.Set;

@JsonTypeName("equalBuckets")
public class EqualBucketsPostAggregator extends ApproximateHistogramPostAggregator
{
  private final int numBuckets;

  @JsonCreator
  public EqualBucketsPostAggregator(
      @JsonProperty("name") String name,
      @JsonProperty("fieldName") String fieldName,
      @JsonProperty("numBuckets") int numBuckets
  )
  {
    super(name, fieldName);
    this.numBuckets = numBuckets;
    if (this.numBuckets <= 1) {
      throw new IAE("Illegal number of buckets[%s], must be > 1", this.numBuckets);
    }
  }

  @Override
  public Set<String> getDependentFields()
  {
    return Sets.newHashSet(fieldName);
  }

  @Override
  public Object compute(Map<String, Object> values)
  {
    ApproximateHistogram ah = (ApproximateHistogram) values.get(fieldName);
    return ah.toHistogram(numBuckets);
  }

  /**
   * actual type is {@link Histogram}

View on GitHub (pinned to 9b90983fd2)