elastic/elasticsearch · error · IllegalStateException

[${name}] is missing : filters parameter

Error message

[${name}] is missing : filters parameter

What it means

Thrown by AdjacencyMatrixAggregationBuilder.checkConsistency when the filters list is null or empty. The adjacency_matrix aggregation requires at least one keyed filter to build the matrix of co-occurring buckets; without filters the aggregation is undefined. The check fires during validation/rewrite of the builder.

Source

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

        separator = in.readString();
        filters = new ArrayList<>(filtersSize);
        for (int i = 0; i < filtersSize; i++) {
            filters.add(new KeyedFilter(in));
        }
    }

    @Override
    protected void doWriteTo(StreamOutput out) throws IOException {
        out.writeVInt(filters.size());
        out.writeString(separator);
        for (KeyedFilter keyedFilter : filters) {
            keyedFilter.writeTo(out);
        }
    }

    private void checkConsistency() {
        if ((filters == null) || (filters.size() == 0)) {
            throw new IllegalStateException("[" + name + "] is missing : " + FILTERS_FIELD.getPreferredName() + " parameter");
        }
    }

    private void setFiltersAsMap(Map<String, QueryBuilder> filters) {
        // Convert uniquely named objects into internal KeyedFilters
        this.filters = new ArrayList<>(filters.size());
        for (Entry<String, QueryBuilder> kv : filters.entrySet()) {
            this.filters.add(new KeyedFilter(kv.getKey(), kv.getValue()));
        }
        // internally we want to have a fixed order of filters, regardless of
        // the order of the filters in the request
        this.filters.sort(Comparator.comparing(KeyedFilter::key));
    }

    private AdjacencyMatrixAggregationBuilder setFiltersAsList(List<KeyedFilter> filters) {
        this.filters = new ArrayList<>(filters);
        // internally we want to have a fixed order of filters, regardless of
        // the order of the filters in the request

View on GitHub (pinned to db6a809a66)

Solutions

1. Provide at least one keyed filter: `adjacencyMatrix("name", filters)` where filters is non-empty.
2. Validate the filters map is non-empty before constructing the aggregation.
3. Check the REST request body contains a non-empty `filters` object.
4. Review conditional logic that may bypass setting filters.

Example fix

// before
new AdjacencyMatrixAggregationBuilder("matrix").build();
// after
Map<String,QueryBuilder> f = Map.of("a", QueryBuilders.termQuery("t","a"));
new AdjacencyMatrixAggregationBuilder("matrix", f).build();

if (filters == null || filters.isEmpty()) {
  throw new IllegalArgumentException("adjacency_matrix requires at least one filter");
}
new AdjacencyMatrixAggregationBuilder("name", filters).build();

When it happens

Trigger: Constructing an `adjacency_matrix` aggregation and calling build() without ever calling filters(...)/setFiltersAsList(...). Submitting a request body with an empty `filters` object. Programmatic construction that conditionally skips setting filters.

Common situations: Templated aggregation builders where the filters are populated conditionally and the condition is false. Refactoring that removes the filters wiring. REST requests with malformed aggregation bodies (filters key omitted).

Related errors

• [separator] must not be null: [${name}]
• [key] must not be null
• [filter] must not be null
• Number of filters is too large, must be less than or equal t
• minimum_interval must be one of [{ALLOWED_INTERVALS.values()

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