What causes "[bitmap_terms] requires a [value]" in elastic/elasticsearch?

Add the "value" key with a base64-encoded serialized RoaringBitmap.

elastic/elasticsearch · error · ParsingException

[bitmap_terms] requires a [value]

Error message

[bitmap_terms] requires a [value]

What it means

Thrown after parsing completes if no "value" key was supplied. The value must be a base64-encoded serialized RoaringBitmap; its absence is caught post-parse as a ParsingException.

Source

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

                    queryName = parser.text();
                } else {
                    throw new ParsingException(
                        parser.getTokenLocation(),
                        "[" + NAME + "] query does not support [" + currentFieldName + "]"
                    );
                }
            } else {
                throw new ParsingException(
                    parser.getTokenLocation(),
                    "[" + NAME + "] unknown token [" + token + "] after [" + currentFieldName + "]"
                );
            }
        }
        if (fieldName == null) {
            throw new ParsingException(parser.getTokenLocation(), "[" + NAME + "] requires a [field]");
        }
        if (value == null) {
            throw new ParsingException(parser.getTokenLocation(), "[" + NAME + "] requires a [value]");
        }
        return new BitmapTermsQueryBuilder(fieldName, value).boost(boost).queryName(queryName);
    }

    @Override
    public String getWriteableName() {
        return NAME;
    }

    @Override
    protected Query doToQuery(SearchExecutionContext context) throws IOException {
        MappedFieldType fieldType = context.getFieldType(fieldName);
        if (!(fieldType instanceof NumberFieldMapper.NumberFieldType numberFieldType)
            || (numberFieldType.numberType() != NumberFieldMapper.NumberType.INTEGER
                && numberFieldType.numberType() != NumberFieldMapper.NumberType.LONG)
            || (numberFieldType.isIndexedWithPoints() == false && numberFieldType.isIndexedWithTerms() == false)) {
            throw new IllegalArgumentException(
                "[bitmap_terms] query is not supported on field ["

View on GitHub (pinned to db6a809a66)

Solutions

Add the "value" key with a base64-encoded serialized RoaringBitmap.
Confirm the client serialization pipeline actually populates the value before issuing the query.

Example fix

// before
{"bitmap_terms":{"field":"uid"}}
// after
{"bitmap_terms":{"field":"uid","value":"PGJpdG1hcD4="}}

Defensive patterns

Strategy: validation

Validate before calling

if (!body.value || typeof body.value !== "string") {
  throw new Error("bitmap_terms requires a [value]");
}

Prevention

Run the bitmap serialization to completion before attaching the value.
Assert the value is a non-empty base64 string prior to send.

When it happens

Trigger: Sending `{"bitmap_terms":{"field":"uid"}}` with no value, or an empty body. Any body missing the "value" key triggers it after the parse loop.

Common situations: Computing the bitmap client-side and forgetting to attach it; serialization bug that yields an empty value string is NOT this error (empty string is non-null and passes here, failing later at base64 decode).

Related errors

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