elastic/elasticsearch · error · IllegalArgumentException

Number of filters is too large, must be less than or equal t

Error message

Number of filters is too large, must be less than or equal to: [${maxFilters}] but was [${filters.size()}].  You can increase this limit by scaling up your java heap

What it means

Thrown by AdjacencyMatrixAggregationBuilder.doBuild when the number of filters exceeds IndexSearcher.getMaxClauseCount() (default 1024). The adjacency_matrix aggregation creates N boolean clauses (one per filter plus pair combinations), so the count is bounded by the same limit that protects boolean queries from clause explosion. The message suggests scaling heap because the limit is often raised via JVM/system configuration.

Source

Thrown at modules/aggregations/src/main/java/org/elasticsearch/aggregations/bucket/adjacency/AdjacencyMatrixAggregationBuilder.java:207

        boolean modified = false;
        List<KeyedFilter> rewrittenFilters = new ArrayList<>(filters.size());
        for (KeyedFilter kf : filters) {
            QueryBuilder rewritten = Rewriteable.rewrite(kf.filter(), queryRewriteContext);
            modified = modified || rewritten != kf.filter();
            rewrittenFilters.add(new KeyedFilter(kf.key(), rewritten));
        }
        if (modified) {
            return new AdjacencyMatrixAggregationBuilder(name).separator(separator).setFiltersAsList(rewrittenFilters);
        }
        return this;
    }

    @Override
    protected AggregatorFactory doBuild(AggregationContext context, AggregatorFactory parent, Builder subFactoriesBuilder)
        throws IOException {
        int maxFilters = IndexSearcher.getMaxClauseCount();
        if (filters.size() > maxFilters) {
            throw new IllegalArgumentException(
                "Number of filters is too large, must be less than or equal to: ["
                    + maxFilters
                    + "] but was ["
                    + filters.size()
                    + "].  "
                    + "You can increase this limit by scaling up your java heap"
            );
        }
        return new AdjacencyMatrixAggregatorFactory(name, filters, separator, context, parent, subFactoriesBuilder, metadata);
    }

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

    @Override
    protected XContentBuilder internalXContent(XContentBuilder builder, Params params) throws IOException {

View on GitHub (pinned to db6a809a66)

Solutions

1. Reduce the number of filters to at or below the current max_clause_count (default 1024).
2. Raise the limit via the setting `indices.query.bool.max_clause_count` on each node — note this requires adequate heap and increases memory pressure on boolean queries cluster-wide.
3. Pre-filter to the most significant categories before building the adjacency_matrix.
4. Consider sampling or a different aggregation strategy if the cardinality is genuinely very high.

Example fix

// before: 2000 filters
// after: raise the limit in elasticsearch.yml
indices.query.bool.max_clause_count: 4096
// and/or reduce filters to the top-N by frequency

int max = org.apache.lucene.search.IndexSearcher.getMaxClauseCount();
if (filters.size() > max) {
  throw new IllegalArgumentException("too many filters (" + filters.size() + " > " + max + ")");
}

When it happens

Trigger: Building an adjacency_matrix aggregation with more than `indices.query.bool.max_clause_count` filters (default 1024). Submitting a request with a dynamically generated filters map that grows past the limit.

Common situations: Analyzing co-occurrence across many categories (e.g. thousands of tags, topics, or segments). Auto-generated aggregations from user-selected facets. Environments where the max_clause_count setting has not been tuned for heavy boolean workloads.

Related errors

• buckets must be less than {bucketCeiling}
• [${name}] is missing : filters parameter
• [separator] must not be null: [${name}]
• [key] must not be null
• [filter] must not be null

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