{"record":{"id":"138660e8eb9360fa","repo":"elastic/elasticsearch","slug":"buckets-must-be-less-than-bucketceiling","errorCode":null,"errorMessage":"buckets must be less than {bucketCeiling}","messagePattern":"buckets must be less than (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/aggregations/src/main/java/org/elasticsearch/aggregations/bucket/histogram/AutoDateHistogramAggregationBuilder.java","lineNumber":211,"sourceCode":"    protected ValuesSourceAggregatorFactory innerBuild(\n        AggregationContext context,\n        ValuesSourceConfig config,\n        AggregatorFactory parent,\n        Builder subFactoriesBuilder\n    ) throws IOException {\n        AutoDateHistogramAggregatorSupplier aggregatorSupplier = context.getValuesSourceRegistry().getAggregator(REGISTRY_KEY, config);\n\n        RoundingInfo[] roundings = buildRoundings(timeZone(), getMinimumIntervalExpression());\n        int maxRoundingInterval = Arrays.stream(roundings, 0, roundings.length - 1)\n            .map(rounding -> rounding.innerIntervals)\n            .flatMapToInt(Arrays::stream)\n            .reduce(Integer::max)\n            .getAsInt();\n        Settings settings = context.getIndexSettings().getNodeSettings();\n        int maxBuckets = MultiBucketConsumerService.MAX_BUCKET_SETTING.get(settings);\n        int bucketCeiling = maxBuckets / maxRoundingInterval;\n        if (numBuckets > bucketCeiling) {\n            throw new IllegalArgumentException(NUM_BUCKETS_FIELD.getPreferredName() + \" must be less than \" + bucketCeiling);\n        }\n        return new AutoDateHistogramAggregatorFactory(\n            name,\n            config,\n            numBuckets,\n            roundings,\n            context,\n            parent,\n            subFactoriesBuilder,\n            metadata,\n            aggregatorSupplier\n        );\n    }\n\n    static Rounding createRounding(Rounding.DateTimeUnit interval, ZoneId timeZone) {\n        Rounding.Builder tzRoundingBuilder = Rounding.builder(interval);\n        if (timeZone != null) {\n            tzRoundingBuilder.timeZone(timeZone);","sourceCodeStart":193,"sourceCodeEnd":229,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/modules/aggregations/src/main/java/org/elasticsearch/aggregations/bucket/histogram/AutoDateHistogramAggregationBuilder.java#L193-L229","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reduce the requested `buckets` count to fit under the computed ceiling.","Raise `search.max_buckets` (cluster setting) to accommodate the desired resolution, ensuring heap can support it.","Loosen minimum_interval (e.g. from second to minute) to lower the inner-interval multiplier and raise the effective ceiling.","Narrow the query time range so fewer buckets are needed."],"exampleFix":"// before: buckets=70000 with default max_buckets\n// after: raise the limit and/or reduce buckets\nPUT /_cluster/settings { \"persistent\": { \"search.max_buckets\": 100000 } }","handlingStrategy":"validation","validationCode":"int maxBuckets = MultiBucketConsumerService.MAX_BUCKET_SETTING.get(settings);\nint ceiling = maxBuckets / maxRoundingInterval;\nif (numBuckets > ceiling) {\n  throw new IllegalArgumentException(\"buckets \" + numBuckets + \" exceeds ceiling \" + ceiling);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Factor in search.max_buckets and the chosen minimum_interval when sizing buckets.","Narrow query time ranges for high-resolution requests.","Raise search.max_buckets only with adequate heap."],"tags":["aggregations","auto-date-histogram","limits","max-buckets","performance"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}