elastic/elasticsearch · error · IllegalArgumentException

buckets must be less than {bucketCeiling}

Error message

buckets must be less than {bucketCeiling}

What it means

Thrown by AutoDateHistogramAggregationBuilder.innerBuild when the requested numBuckets exceeds `bucketCeiling`, computed as search.max_buckets divided by the maximum inner-interval count of the roundings in use. This prevents the auto_date_histogram from materializing more buckets than the cluster's max bucket limit allows at the chosen minimum interval.

Source

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

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

        RoundingInfo[] roundings = buildRoundings(timeZone(), getMinimumIntervalExpression());
        int maxRoundingInterval = Arrays.stream(roundings, 0, roundings.length - 1)
            .map(rounding -> rounding.innerIntervals)
            .flatMapToInt(Arrays::stream)
            .reduce(Integer::max)
            .getAsInt();
        Settings settings = context.getIndexSettings().getNodeSettings();
        int maxBuckets = MultiBucketConsumerService.MAX_BUCKET_SETTING.get(settings);
        int bucketCeiling = maxBuckets / maxRoundingInterval;
        if (numBuckets > bucketCeiling) {
            throw new IllegalArgumentException(NUM_BUCKETS_FIELD.getPreferredName() + " must be less than " + bucketCeiling);
        }
        return new AutoDateHistogramAggregatorFactory(
            name,
            config,
            numBuckets,
            roundings,
            context,
            parent,
            subFactoriesBuilder,
            metadata,
            aggregatorSupplier
        );
    }

    static Rounding createRounding(Rounding.DateTimeUnit interval, ZoneId timeZone) {
        Rounding.Builder tzRoundingBuilder = Rounding.builder(interval);
        if (timeZone != null) {
            tzRoundingBuilder.timeZone(timeZone);

View on GitHub (pinned to db6a809a66)

Solutions

1. Reduce the requested `buckets` count to fit under the computed ceiling.
2. Raise `search.max_buckets` (cluster setting) to accommodate the desired resolution, ensuring heap can support it.
3. Loosen minimum_interval (e.g. from second to minute) to lower the inner-interval multiplier and raise the effective ceiling.
4. Narrow the query time range so fewer buckets are needed.

Example fix

// before: buckets=70000 with default max_buckets
// after: raise the limit and/or reduce buckets
PUT /_cluster/settings { "persistent": { "search.max_buckets": 100000 } }

int maxBuckets = MultiBucketConsumerService.MAX_BUCKET_SETTING.get(settings);
int ceiling = maxBuckets / maxRoundingInterval;
if (numBuckets > ceiling) {
  throw new IllegalArgumentException("buckets " + numBuckets + " exceeds ceiling " + ceiling);
}

When it happens

Trigger: Requesting a large `buckets` value (e.g. 65000) while search.max_buckets is at default (65536) and the rounding granularity forces many inner intervals. Lowering search.max_buckets below the requested bucket count scaled by the rounding's inner interval count.

Common situations: Dashboards requesting high-resolution auto_date_histogram over long time ranges. Environments where search.max_buckets has been reduced for memory reasons. Tight minimum_interval (e.g. second) combined with large bucket requests.

Related errors

• Number of filters is too large, must be less than or equal t
• minimum_interval must be one of [{ALLOWED_INTERVALS.values()
• buckets must be greater than 0 for [{name}]
• dateTimeUnit must be one of {ALLOWED_INTERVALS.keySet()}
• cancelled

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