elastic/elasticsearch · error · IllegalArgumentException

buckets must be greater than 0 for [{name}]

Error message

buckets must be greater than 0 for [{name}]

What it means

Thrown by AutoDateHistogramAggregationBuilder.setNumBuckets when numBuckets is <= 0. The auto_date_histogram aggregation requires a positive target bucket count because it dynamically sizes rounding intervals to produce approximately that many buckets; zero or negative is meaningless.

Source

Thrown at modules/aggregations/src/main/java/org/elasticsearch/aggregations/bucket/histogram/AutoDateHistogramAggregationBuilder.java:181

    }

    public String getMinimumIntervalExpression() {
        return minimumIntervalExpression;
    }

    public AutoDateHistogramAggregationBuilder setMinimumIntervalExpression(String minimumIntervalExpression) {
        if (minimumIntervalExpression != null && ALLOWED_INTERVALS.containsValue(minimumIntervalExpression) == false) {
            throw new IllegalArgumentException(
                MINIMUM_INTERVAL_FIELD.getPreferredName() + " must be one of [" + ALLOWED_INTERVALS.values() + "]"
            );
        }
        this.minimumIntervalExpression = minimumIntervalExpression;
        return this;
    }

    public AutoDateHistogramAggregationBuilder setNumBuckets(int numBuckets) {
        if (numBuckets <= 0) {
            throw new IllegalArgumentException(NUM_BUCKETS_FIELD.getPreferredName() + " must be greater than 0 for [" + name + "]");
        }
        this.numBuckets = numBuckets;
        return this;
    }

    @Override
    public BucketCardinality bucketCardinality() {
        return BucketCardinality.MANY;
    }

    @Override
    protected ValuesSourceAggregatorFactory innerBuild(
        AggregationContext context,
        ValuesSourceConfig config,
        AggregatorFactory parent,
        Builder subFactoriesBuilder
    ) throws IOException {
        AutoDateHistogramAggregatorSupplier aggregatorSupplier = context.getValuesSourceRegistry().getAggregator(REGISTRY_KEY, config);

View on GitHub (pinned to db6a809a66)

Solutions

1. Set buckets to a positive integer (the default is 10).
2. Validate configuration values are >= 1 before constructing the aggregation.
3. Coerce zero/negative to the default if the value is optional.

Example fix

// before
{"auto_date_histogram":{"field":"@timestamp","buckets":0}}
// after
{"auto_date_histogram":{"field":"@timestamp","buckets":10}}

if (numBuckets <= 0) {
  throw new IllegalArgumentException("buckets must be > 0");
}

When it happens

Trigger: Calling setNumBuckets(0) or setNumBuckets(-1). Submitting a REST request with `"buckets": 0` or a negative value. Defaulting from an unset/zero-valued configuration variable.

Common situations: Configuration driven by a variable that defaults to 0. User input parsed as integer without a positivity check. Tests passing boundary values.

Related errors

• minimum_interval must be one of [{ALLOWED_INTERVALS.values()
• [size] must be greater than 0. Found [{size}] in [{name}]
• [${name}] is missing : filters parameter
• [separator] must not be null: [${name}]
• [key] must not be null

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/68d3c5ffdc1f42d1. Report an issue: GitHub.