elastic/elasticsearch · error · IllegalArgumentException

[bitmap_terms] query is not supported on field [{}]: only su

Error message

[bitmap_terms] query is not supported on field [{}]: only supported on [integer] and [long] fields indexed with points or terms

What it means

Thrown by doToQuery at execution time when the resolved field type is not a NumberFieldType of integer or long, or when the field is not indexed with points or terms. bitmap_terms only operates on indexed numeric integer/long fields because it merges the supplied bitmap against the point or terms index structure.

Source

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

        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 ["
                    + fieldName
                    + "]: only supported on [integer] and [long] fields indexed with points or terms"
            );
        }
        byte[] bitmapBytes;
        try {
            bitmapBytes = Base64.getDecoder().decode(value);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("[bitmap_terms] query expects a base64-encoded RoaringBitmap value", e);
        }
        BitmapValues values = switch (numberFieldType.numberType()) {
            case INTEGER -> integerValues(bitmapBytes);
            case LONG -> longValues(bitmapBytes);
            default -> throw new AssertionError("unexpected number type [" + numberFieldType.numberType() + "]");
        };
        // The two queries differ only in which index structure they merge against; the field's width
        // is carried by the BitmapValues.

View on GitHub (pinned to db6a809a66)

Solutions

1. Target a field mapped as integer or long with index:true (or indexed via points, the default for numerics).
2. Correct the field name in the query to match the actual indexed numeric field.
3. Reindex or update the mapping so the field is indexed with points or terms before running bitmap_terms.

Example fix

// before mapping
"uid":{"type":"keyword"}
// after mapping
"uid":{"type":"long","index":true}

// Fetch the mapping and confirm the field is integer/long and indexed.
const mapping = await es.indices.getMapping({ index });
const prop = mapping[index].mappings.properties[fieldName];
if (!prop || !['integer','long'].includes(prop.type)) {
  throw new Error(`bitmap_terms requires integer/long field, got ${prop?.type}`);
}
if (prop.index === false) {
  throw new Error(`field [${fieldName}] is not indexed`);
}

When it happens

Trigger: Pointing bitmap_terms at a keyword, text, float, double, boolean, or ip field; an integer/long field with index:false; an unindexed (doc_values-only) numeric field. Also when the field does not exist in the mapping (getFieldType may resolve to null and the instanceof check fails).

Common situations: Mismatched field name between query and mapping; field configured with index:false for storage-only; using a long-backed dimension field that was not indexed; version/mapping drift after a reindex.

Related errors

• found Z value [
• [bitmap_terms] query does not support [{}]
• [bitmap_terms] unknown token [{}] after [{}]
• [bitmap_terms] requires a [field]
• [bitmap_terms] requires a [value]

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