{"record":{"id":"48f7c840f5a91244","repo":"elastic/elasticsearch","slug":"bitmap-terms-query-value-is-not-a-valid-serializ-48f7c8","errorCode":null,"errorMessage":"[bitmap_terms] query value is not a valid serialized 64-bit RoaringBitmap in the portable format","messagePattern":"\\[bitmap_terms\\] query value is not a valid serialized 64-bit RoaringBitmap in the portable format","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"modules/bitmap/src/main/java/org/elasticsearch/index/query/bitmapterms/BitmapTermsQueryBuilder.java","lineNumber":201,"sourceCode":"        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(\n                \"[bitmap_terms] query on [long] field only supports non-negative values (0 to 9223372036854775807)\"\n            );\n        }\n        return bitmap;\n    }\n\n    @Override\n    protected int doHashCode() {\n        return Objects.hash(fieldName, value);\n    }\n\n    @Override","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/modules/bitmap/src/main/java/org/elasticsearch/index/query/bitmapterms/BitmapTermsQueryBuilder.java#L183-L219","documentation":"Thrown by longValues when LongBitmap.deserializePortable fails on the decoded bytes. The bytes were valid base64 but do not form a valid 64-bit RoaringBitmap in the portable format (the format produced by Roaring64NavigableMap.serializePortable). A common cause is supplying bytes from the non-portable serialize() method, which uses a different layout.","triggerScenarios":"Calling Roaring64NavigableMap.serialize (default/non-portable) instead of serializePortable on the client; supplying a 32-bit bitmap payload to a long field; truncated or version-mismatched bytes.","commonSituations":"Java client forgets to call serializePortable specifically; pyroaring version mismatch; copy between integer/long fields without re-serializing.","solutions":["For long fields, call Roaring64NavigableMap.serializePortable (java) or pyroaring BitMap64.serialize, then base64-encode.","Do not reuse a 32-bit bitmap payload on a long field; regenerate in 64-bit portable format.","Confirm the client Roaring library version produces the portable layout the server expects."],"exampleFix":"// before: non-portable serialize\nbytes = bitmap.serialize()\n// after: portable format for long field\nbytes = bitmap.serializePortable()","handlingStrategy":"validation","validationCode":"// Round-trip the 64-bit bitmap via deserializePortable on the client.\nimport org.roaringbitmap.longlong.Roaring64NavigableMap;\nbyte[] bytes = bitmap.serializePortable();\nRoaring64NavigableMap probe = new Roaring64NavigableMap();\nprobe.deserializePortable(DataInput.wrap(bytes));\nString value = Base64.getEncoder().encodeToString(bytes);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["For long fields always call serializePortable, not serialize.","Round-trip deserializePortable locally to validate format before sending."],"tags":["bitmap-terms","roaring-bitmap","serialization","elasticsearch"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}