{"record":{"id":"f34770334d75a1ff","repo":"elastic/elasticsearch","slug":"bitmap-terms-query-is-not-supported-on-field","errorCode":null,"errorMessage":"[bitmap_terms] query is not supported on field [{}]: only supported on [integer] and [long] fields indexed with points or terms","messagePattern":"\\[bitmap_terms\\] query is not supported on field \\[(.+?)\\]: only supported on \\[integer\\] and \\[long\\] fields indexed with points or terms","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"modules/bitmap/src/main/java/org/elasticsearch/index/query/bitmapterms/BitmapTermsQueryBuilder.java","lineNumber":156,"sourceCode":"        if (value == null) {\n            throw new ParsingException(parser.getTokenLocation(), \"[\" + NAME + \"] requires a [value]\");\n        }\n        return new BitmapTermsQueryBuilder(fieldName, value).boost(boost).queryName(queryName);\n    }\n\n    @Override\n    public String getWriteableName() {\n        return NAME;\n    }\n\n    @Override\n    protected Query doToQuery(SearchExecutionContext context) throws IOException {\n        MappedFieldType fieldType = context.getFieldType(fieldName);\n        if (!(fieldType instanceof NumberFieldMapper.NumberFieldType numberFieldType)\n            || (numberFieldType.numberType() != NumberFieldMapper.NumberType.INTEGER\n                && numberFieldType.numberType() != NumberFieldMapper.NumberType.LONG)\n            || (numberFieldType.isIndexedWithPoints() == false && numberFieldType.isIndexedWithTerms() == false)) {\n            throw new IllegalArgumentException(\n                \"[bitmap_terms] query is not supported on field [\"\n                    + fieldName\n                    + \"]: only supported on [integer] and [long] fields indexed with points or terms\"\n            );\n        }\n        byte[] bitmapBytes;\n        try {\n            bitmapBytes = Base64.getDecoder().decode(value);\n        } catch (IllegalArgumentException e) {\n            throw new IllegalArgumentException(\"[bitmap_terms] query expects a base64-encoded RoaringBitmap value\", e);\n        }\n        BitmapValues values = switch (numberFieldType.numberType()) {\n            case INTEGER -> integerValues(bitmapBytes);\n            case LONG -> longValues(bitmapBytes);\n            default -> throw new AssertionError(\"unexpected number type [\" + numberFieldType.numberType() + \"]\");\n        };\n        // The two queries differ only in which index structure they merge against; the field's width\n        // is carried by the BitmapValues.","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/modules/bitmap/src/main/java/org/elasticsearch/index/query/bitmapterms/BitmapTermsQueryBuilder.java#L138-L174","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Target a field mapped as integer or long with index:true (or indexed via points, the default for numerics).","Correct the field name in the query to match the actual indexed numeric field.","Reindex or update the mapping so the field is indexed with points or terms before running bitmap_terms."],"exampleFix":"// before mapping\n\"uid\":{\"type\":\"keyword\"}\n// after mapping\n\"uid\":{\"type\":\"long\",\"index\":true}","handlingStrategy":"validation","validationCode":"// Fetch the mapping and confirm the field is integer/long and indexed.\nconst mapping = await es.indices.getMapping({ index });\nconst prop = mapping[index].mappings.properties[fieldName];\nif (!prop || !['integer','long'].includes(prop.type)) {\n  throw new Error(`bitmap_terms requires integer/long field, got ${prop?.type}`);\n}\nif (prop.index === false) {\n  throw new Error(`field [${fieldName}] is not indexed`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pre-flight check the target field mapping before issuing bitmap_terms.","Keep field naming consistent between query construction and index template."],"tags":["bitmap-terms","mapping","field-type","elasticsearch"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}