elastic/elasticsearch · error · IllegalArgumentException

[bitmap_terms] field name cannot be null or empty

Error message

[bitmap_terms] field name cannot be null or empty

What it means

BitmapTermsQueryBuilder constructor validates fieldName up-front: null or isBlank() (empty or whitespace-only) throws IllegalArgumentException. This is the leaf query used by the bitmap_terms query type. The check is a pure precondition before any field is resolved against a mapping.

Source

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

 *   "bitmap_terms": {
 *     "field": "my_long_field",
 *     "value": "<base64-encoded bitmap>"
 *   }
 * }
 * }</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);

View on GitHub (pinned to db6a809a66)

Solutions

1. Always supply a non-blank field name when constructing the query.
2. Validate fieldName at the application boundary before passing it to the builder.
3. For REST requests, ensure the 'field' key is present and non-empty in the bitmap_terms body.

Example fix

// before
new BitmapTermsQueryBuilder(null, value)
new BitmapTermsQueryBuilder("  ", value)
// after
new BitmapTermsQueryBuilder("category_id", value)

static String requireFieldName(String f) {
  if (f == null || f.isBlank()) throw new IllegalArgumentException("field required");
  return f;
}

// Narrow a String to a non-blank field name before constructing the query
static boolean isUsableFieldName(String f) {
  return f != null && !f.isBlank();
}

When it happens

Trigger: Constructing a BitmapTermsQueryBuilder via the Java API or the REST query DSL with a missing, null, or whitespace field name — e.g. sending {"bitmap_terms": {"value": "x"}} with no 'field', or an explicit null field.

Common situations: Programmatic query building where the field name comes from user input that was not validated; JSON deserialisation edge case where the field key was omitted; templated query that left field blank.

Related errors

• [bitmap_terms] value cannot be null
• 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/82cd9522d6d5f641. Report an issue: GitHub.