What causes "at least 2 bins expected" in apache/druid?

apache/druid · error · IllegalArgumentException

at least 2 bins expected

Error message

at least 2 bins expected

What it means

KllDoublesSketchToHistogramPostAggregator.compute derives the bin count from splitPoints (length+1), numBins, or the default, and throws IllegalArgumentException when fewer than 2 bins result. A histogram needs at least two edges/bins to be meaningful. The check also fires when a single split point (1 split => 2 bins is fine) yields an invalid count or numBins < 2 was requested.

Source

Thrown at extensions-core/datasketches/src/main/java/org/apache/druid/query/aggregation/datasketches/kll/KllDoublesSketchToHistogramPostAggregator.java:73

      @JsonProperty("numBins") @Nullable final Integer numBins)
  {
    this.name = Preconditions.checkNotNull(name, "name is null");
    this.field = Preconditions.checkNotNull(field, "field is null");
    this.splitPoints = splitPoints;
    this.numBins = numBins;
    if (splitPoints != null && numBins != null) {
      throw new IAE("Cannot accept both 'splitPoints' and 'numBins'");
    }
  }

  @Override
  public Object compute(final Map<String, Object> combinedAggregators)
  {
    final KllDoublesSketch sketch = (KllDoublesSketch) field.compute(combinedAggregators);
    final int numBins = this.splitPoints != null ? this.splitPoints.length + 1 :
        (this.numBins != null ? this.numBins.intValue() : DEFAULT_NUM_BINS);
    if (numBins < 2) {
      throw new IAE("at least 2 bins expected");
    }
    if (sketch.isEmpty()) {
      final double[] histogram = new double[numBins];
      Arrays.fill(histogram, Double.NaN);
      return histogram;
    }
    final double[] splitPoints;
    if (this.splitPoints != null) {
      splitPoints = this.splitPoints;
    } else {
      final double min = sketch.getMinItem();
      final double max = sketch.getMaxItem();
      if (min == max) {
        // if min is equal to max, we can't create an array of equally spaced points.
        // all values would go into the first bucket anyway, and the remaining
        // buckets are left as zero.
        final double[] histogram = new double[numBins];
        histogram[0] = sketch.getN();

View on GitHub (pinned to 9b90983fd2)

Solutions

Set numBins to at least 2
Provide at least 1 split point (giving 2 bins) if using splitPoints
Use an empty/null config to fall back to DEFAULT_NUM_BINS instead of forcing a tiny bin count

Example fix

// before
{"type":"kllDoublesSketchToHistogram","name":"h","field":f,"numBins":1}
// after
{"type":"kllDoublesSketchToHistogram","name":"h","field":f,"numBins":10}

Defensive patterns

Strategy: validation

Validate before calling

int bins = splitPoints != null ? splitPoints.length + 1 : (numBins != null ? numBins : 20);
if (bins < 2) throw new IllegalArgumentException("numBins/splitPoints must yield at least 2 bins");

Try / catch

try { result = postAgg.compute(combined); } catch (IllegalArgumentException e) { log.error("Invalid histogram config: {}", e.getMessage()); }

Prevention

Always set numBins >= 2 or supply at least one split point
Guard dynamic spec generators against empty splitPoints arrays
Remember splitPoints.length must be >= 1

When it happens

Trigger: Setting numBins to 0 or 1; supplying an empty splitPoints array (length 0 => 1 bin); passing null/empty splitPoints with a numBins below 2 in compute.

Common situations: Misconfigured spec with numBins: 1 or empty splitPoints: []; a dynamic spec generator producing empty arrays; users thinking splitPoints means edge count including outer bounds.

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

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