elastic/elasticsearch · error · IllegalArgumentException

[key] must not be null

Error message

[key] must not be null

What it means

Thrown by the KeyedFilter constructor (inside AdjacencyMatrixAggregator) when the `key` argument is null. KeyedFilter pairs a label with a query for the adjacency_matrix; a null key would corrupt the bucket-naming logic and map ordering, so it is rejected immediately.

Source

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

 * Aggregation for adjacency matrices.
 *
 */
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 {

View on GitHub (pinned to db6a809a66)

Solutions

1. Provide a non-null, non-empty key for every filter in the adjacency_matrix.
2. Validate the filters map for null/empty keys before submission.
3. Sanitize the request body to ensure each filter object has a distinct label.

Example fix

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

if (key == null || key.isEmpty()) {
  throw new IllegalArgumentException("filter key must be non-empty");
}

When it happens

Trigger: Constructing `new KeyedFilter(null, query)` programmatically, or submitting an adjacency_matrix request where a filter entry has a null/missing key. Reached via the PARSER when the aggregation name resolution yields null for a filter's key.

Common situations: REST requests where a filter object is keyed by an empty or whitespace string that downstream resolves to null. Programmatic builders using a map that permits null keys. Deserialization of malformed payloads.

Related errors

• [separator] must not be null: [${name}]
• [filter] 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/ebe2b029c65253f8. Report an issue: GitHub.