elastic/elasticsearch · error · ParsingException

[bitmap_terms] query does not support [{}]

Error message

[bitmap_terms] query does not support [{}]

What it means

Thrown by BitmapTermsQueryBuilder.fromXContent when the query JSON body contains a field name other than the four supported ones (field, value, boost, _name). The parser walks the object and rejects any unrecognized key at parse time, before any query execution. This is the standard Elasticsearch mechanism for surfacing typos or unsupported options in a query DSL body.

Source

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

        float boost = DEFAULT_BOOST;
        String queryName = null;

        XContentParser.Token token;
        String currentFieldName = null;
        while ((token = parser.nextToken()) != XContentParser.Token.END_OBJECT) {
            if (token == XContentParser.Token.FIELD_NAME) {
                currentFieldName = parser.currentName();
            } else if (token.isValue()) {
                if ("field".equals(currentFieldName)) {
                    fieldName = parser.text();
                } else if ("value".equals(currentFieldName)) {
                    value = parser.text();
                } else if (BOOST_FIELD.match(currentFieldName, parser.getDeprecationHandler())) {
                    boost = parser.floatValue();
                } else if (NAME_FIELD.match(currentFieldName, parser.getDeprecationHandler())) {
                    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);

View on GitHub (pinned to db6a809a66)

Solutions

1. Remove the unsupported key from the bitmap_terms body; only field, value, boost, and _name are accepted.
2. Re-check the query against the BitmapTermsQueryBuilder Javadoc / doXContent output which serializes exactly field, value, boost, _name.
3. If you need scoring control, use the supported boost / _name rather than other query options.

Example fix

// before
{"bitmap_terms":{"field":"uid","value":"PGJpdG1hcD4=","minimum_should_match":1}}
// after
{"bitmap_terms":{"field":"uid","value":"PGJpdG1hcD4=","boost":1.0}}

// Validate the bitmap_terms query body keys before sending.
const ALLOWED = new Set(["field", "value", "boost", "_name"]);
function validateBitmapTerms(body) {
  for (const k of Object.keys(body)) {
    if (!ALLOWED.has(k)) throw new Error(`bitmap_terms does not support [${k}]`);
  }
  if (typeof body.field !== "string") throw new Error("field must be a string");
  if (typeof body.value !== "string") throw new Error("value must be a string");
}

When it happens

Trigger: Issuing a `bitmap_terms` query whose JSON includes an unsupported key, e.g. `{"bitmap_terms":{"field":"f","value":"...","minimum_should_match":1}}` or a typo like `"feild"`. Any key not literally "field", "value", "boost", or "_name" reaches this throw.

Common situations: Copy-pasting a terms/terms_set query body and assuming bitmap_terms shares options; auto-generating query JSON with a schema that drifts from the supported set; typos in field names produced by template engines.

Related errors

• [bitmap_terms] unknown token [{}] after [{}]
• [bitmap_terms] requires a [field]
• [bitmap_terms] requires a [value]
• Unknown geometry type:
• Unknown geometry type: {}

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