elastic/elasticsearch · error · ParsingException

[bitmap_terms] unknown token [{}] after [{}]

Error message

[bitmap_terms] unknown token [{}] after [{}]

What it means

Thrown by BitmapTermsQueryBuilder.fromXContent when the parser encounters a structural token that is neither FIELD_NAME nor a scalar value (e.g. START_OBJECT, START_ARRAY, END_OBJECT in the wrong place). bitmap_terms expects every key to map to a single scalar value; nested objects or arrays are not allowed.

Source

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

            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);
    }

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

View on GitHub (pinned to db6a809a66)

Solutions

1. Ensure field and value are single scalar strings, not arrays or objects.
2. Validate the JSON is a flat object of scalar key/value pairs with a JSON linter before sending.
3. Regenerate the body from a known-good BitmapTermsQueryBuilder via doXContent rather than hand-writing.

Example fix

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

// Ensure all values are scalars, not arrays/objects.
function assertScalarBody(body) {
  for (const [k, v] of Object.entries(body)) {
    if (v !== null && typeof v === "object") {
      throw new Error(`bitmap_terms [${k}] must be a scalar, got ${Array.isArray(v) ? "array" : "object"}`);
    }
  }
}

When it happens

Trigger: Supplying an array or object where a scalar is expected, e.g. `{"bitmap_terms":{"field":["a","b"],"value":"..."}}` or an extra brace producing an unexpected END_OBJECT. Any token where token.isValue() is false and it is not FIELD_NAME triggers it.

Common situations: Treating bitmap_terms like a multi-value terms query and passing arrays; malformed JSON from client serializers that wrap scalars in objects; hand-editing JSON and leaving a dangling brace.

Related errors

• [bitmap_terms] query does not support [{}]
• [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/6fdea30d0dfc93a9. Report an issue: GitHub.