{"record":{"id":"520cf7e77077c50f","repo":"elastic/elasticsearch","slug":"bitmap-terms-query-on-integer-field-only-suppo","errorCode":null,"errorMessage":"[bitmap_terms] query on [integer] field only supports non-negative values (0 to 2147483647)","messagePattern":"\\[bitmap_terms\\] query on \\[integer\\] field only supports non-negative values \\(0 to 2147483647\\)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"modules/bitmap/src/main/java/org/elasticsearch/index/query/bitmapterms/BitmapTermsQueryBuilder.java","lineNumber":189,"sourceCode":"            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.\n        if (numberFieldType.isIndexedWithTerms()) {\n            return new BitmapTermsQuery(fieldName, values);\n        }\n        return new BitmapBKDQuery(fieldName, values);\n    }\n\n    private static IntBitmap integerValues(byte[] bitmapBytes) {\n        IntBitmap bitmap;\n        try {\n            bitmap = IntBitmap.deserialize(bitmapBytes);\n        } catch (Exception e) {\n            throw new IllegalArgumentException(\"[bitmap_terms] query value is not a valid serialized RoaringBitmap\", e);\n        }\n        if (bitmap.hasNegativeValues()) {\n            throw new IllegalArgumentException(\n                \"[bitmap_terms] query on [integer] field only supports non-negative values (0 to 2147483647)\"\n            );\n        }\n        return bitmap;\n    }\n\n    private static LongBitmap longValues(byte[] bitmapBytes) {\n        LongBitmap bitmap;\n        try {\n            bitmap = LongBitmap.deserializePortable(bitmapBytes);\n        } catch (Exception e) {\n            throw new IllegalArgumentException(\n                \"[bitmap_terms] query value is not a valid serialized 64-bit RoaringBitmap in the portable format\",\n                e\n            );\n        }\n        if (bitmap.hasNegativeValues()) {\n            throw new IllegalArgumentException(","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/modules/bitmap/src/main/java/org/elasticsearch/index/query/bitmapterms/BitmapTermsQueryBuilder.java#L171-L207","documentation":"Thrown by integerValues after a successful 32-bit RoaringBitmap deserialize when the bitmap contains any value in the negative int range. integer fields in Elasticsearch are signed 32-bit, but bitmap_terms restricts to the non-negative range [0, 2147483647] because that is the meaningful domain for matching indexed integer point values.","triggerScenarios":"A 32-bit RoaringBitmap that has any of bits in the range interpreted as >= 2^31 set (i.e. values that would be negative java ints), or a bitmap built from unsigned values that overflow into the sign bit.","commonSituations":"Client treats the bitmap as unsigned 32-bit while the field is signed; bit-flip from a hashing step that produces high-bit values.","solutions":["Ensure all values in the 32-bit bitmap are in [0, 2147483647].","If you need values above 2^31-1, switch the field to long and supply a 64-bit portable bitmap.","Filter or reject high-bit values on the producer side before serializing."],"exampleFix":"// before\nbitmap.add(3000000000L) // > Integer.MAX_VALUE\n// after\nlongField mapping + 64-bit portable bitmap containing 3000000000L","handlingStrategy":"validation","validationCode":"// Reject any value above Integer.MAX_VALUE before serializing for an integer field.\nfor (long v : values) {\n  if (v < 0 || v > Integer.MAX_VALUE) {\n    throw new IllegalArgumentException(\"integer bitmap value out of range: \" + v);\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Bound-check all values against [0, Integer.MAX_VALUE] before adding to the bitmap.","Switch to a long field if any value exceeds 2^31-1."],"tags":["bitmap-terms","roaring-bitmap","integer-overflow","elasticsearch"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}