elastic/elasticsearch · error · IllegalArgumentException

[bitmap_terms] value cannot be null

Error message

[bitmap_terms] value cannot be null

What it means

BitmapTermsQueryBuilder constructor's second precondition: the value parameter must not be null (empty string is allowed; only null is rejected). Throws IllegalArgumentException immediately when value == null. Note fieldName is checked first, so a null field surfaces the 1058 message instead.

Source

Thrown at modules/bitmap/src/main/java/org/elasticsearch/index/query/bitmapterms/BitmapTermsQueryBuilder.java:67

 *   }
 * }
 * }</pre>
 */
public class BitmapTermsQueryBuilder extends LeafQueryBuilder<BitmapTermsQueryBuilder> {

    public static final String NAME = "bitmap_terms";

    static final TransportVersion BITMAP_TERMS_QUERY_ADDED = TransportVersion.fromName("bitmap_terms_query_added");

    private final String fieldName;
    private final String value;

    public BitmapTermsQueryBuilder(String fieldName, String value) {
        if (fieldName == null || fieldName.isBlank()) {
            throw new IllegalArgumentException("[bitmap_terms] field name cannot be null or empty");
        }
        if (value == null) {
            throw new IllegalArgumentException("[bitmap_terms] value cannot be null");
        }
        this.fieldName = fieldName;
        this.value = value;
    }

    public BitmapTermsQueryBuilder(StreamInput in) throws IOException {
        super(in);
        this.fieldName = in.readString();
        this.value = in.readString();
    }

    @Override
    protected void doWriteTo(StreamOutput out) throws IOException {
        out.writeString(fieldName);
        out.writeString(value);
    }

    public String fieldName() {

View on GitHub (pinned to db6a809a66)

Solutions

1. Always pass a non-null value (use "" if an empty match is genuinely intended, though that is rarely useful).
2. Validate at the application boundary that value is non-null before constructing the query.
3. For REST requests, ensure the 'value' key is present in the bitmap_terms body.

Example fix

// before
new BitmapTermsQueryBuilder("category_id", null)
// after
String v = userInput == null ? "" : userInput;
new BitmapTermsQueryBuilder("category_id", v);

static String requireValue(String v) {
  if (v == null) throw new IllegalArgumentException("value required");
  return v;
}

// Narrow to a non-null value before constructing the query
static boolean isUsableValue(String v) {
  return v != null;
}

When it happens

Trigger: Constructing a BitmapTermsQueryBuilder with a non-blank field but a null value: new BitmapTermsQueryBuilder("f", null); or a REST request like {"bitmap_terms": {"field": "f"}} with no 'value' key.

Common situations: Passing through an unvalidated user input that may be null; missing 'value' key in JSON; conditional logic that forgot to default the value.

Related errors

• [bitmap_terms] field name cannot be null or empty
• blockSize must be a power of 2 in [{}, {}], got: {}
• [filter] must not be null
• Elasticsearch version is missing from properties.
• Expected elasticsearch version to be numbers only of the for

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