elastic/elasticsearch · error · IllegalArgumentException

[filter] must not be null

Error message

[filter] must not be null

What it means

Thrown by the KeyedFilter constructor (inside AdjacencyMatrixAggregator) when the `filter` (a QueryBuilder) argument is null. Each keyed filter must carry a concrete query; a null query cannot be executed against the index, so construction fails fast.

Source

Thrown at modules/aggregations/src/main/java/org/elasticsearch/aggregations/bucket/adjacency/AdjacencyMatrixAggregator.java:65

public class AdjacencyMatrixAggregator extends BucketsAggregator {

    public static final ParseField FILTERS_FIELD = new ParseField("filters");

    protected static class KeyedFilter implements Writeable, ToXContentFragment {
        private final String key;
        private final QueryBuilder filter;

        public static final NamedObjectParser<KeyedFilter, String> PARSER = (
            XContentParser p,
            String aggName,
            String name) -> new KeyedFilter(name, parseTopLevelQuery(p));

        public KeyedFilter(String key, QueryBuilder filter) {
            if (key == null) {
                throw new IllegalArgumentException("[key] must not be null");
            }
            if (filter == null) {
                throw new IllegalArgumentException("[filter] must not be null");
            }
            this.key = key;
            this.filter = filter;
        }

        /**
         * Read from a stream.
         */
        public KeyedFilter(StreamInput in) throws IOException {
            key = in.readString();
            filter = in.readNamedWriteable(QueryBuilder.class);
        }

        @Override
        public void writeTo(StreamOutput out) throws IOException {
            out.writeString(key);
            out.writeNamedWriteable(filter);
        }

View on GitHub (pinned to db6a809a66)

Solutions

1. Provide a non-null QueryBuilder (e.g. match_all, term, bool) for every keyed filter.
2. Default to matchAllQuery() if a filter genuinely should match everything.
3. Validate each filter's query is non-null before constructing KeyedFilter.

Example fix

// before
new KeyedFilter("k", null);
// after
new KeyedFilter("k", QueryBuilders.matchAllQuery());

if (filter == null) {
  throw new IllegalArgumentException("filter query must not be null");
}
// or default: QueryBuilders.matchAllQuery()

When it happens

Trigger: Constructing `new KeyedFilter(key, null)`. Submitting an adjacency_matrix filter entry whose query body is missing, empty, or unparsable such that the resolved QueryBuilder is null.

Common situations: REST requests with a filter object that omits the query clause. Programmatic builders that pass a query variable which is conditionally null. Ingest-time transformation dropping the query.

Related errors

• [separator] must not be null: [${name}]
• [key] must not be null
• [${name}] is missing : filters parameter
• input cannot be null
• Number of filters is too large, must be less than or equal t

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