elastic/elasticsearch · error · IllegalArgumentException

[bitmap_terms] query on [long] field only supports non-negat

Error message

[bitmap_terms] query on [long] field only supports non-negative values (0 to 9223372036854775807)

What it means

Thrown by longValues after a successful 64-bit portable deserialize when the bitmap contains negative values. long fields are signed 64-bit but bitmap_terms restricts to the non-negative range [0, 9223372036854775807].

Source

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

            throw new IllegalArgumentException(
                "[bitmap_terms] query on [integer] field only supports non-negative values (0 to 2147483647)"
            );
        }
        return bitmap;
    }

    private static LongBitmap longValues(byte[] bitmapBytes) {
        LongBitmap bitmap;
        try {
            bitmap = LongBitmap.deserializePortable(bitmapBytes);
        } catch (Exception e) {
            throw new IllegalArgumentException(
                "[bitmap_terms] query value is not a valid serialized 64-bit RoaringBitmap in the portable format",
                e
            );
        }
        if (bitmap.hasNegativeValues()) {
            throw new IllegalArgumentException(
                "[bitmap_terms] query on [long] field only supports non-negative values (0 to 9223372036854775807)"
            );
        }
        return bitmap;
    }

    @Override
    protected int doHashCode() {
        return Objects.hash(fieldName, value);
    }

    @Override
    protected boolean doEquals(BitmapTermsQueryBuilder other) {
        return Objects.equals(fieldName, other.fieldName) && Objects.equals(value, other.value);
    }

    @Override
    public TransportVersion getMinimalSupportedVersion() {

View on GitHub (pinned to db6a809a66)

Solutions

Ensure all values in the 64-bit bitmap are in [0, 9223372036854775807].
Mask or fold high-bit values on the producer side before serializing.
If the domain genuinely needs the full unsigned range, redesign to split into two signed fields.

Example fix

// before
bitmap.addLong(0xF000000000000000L) // high bit set, negative as signed long
// after
bitmap.addLong(0x7000000000000000L) // within non-negative signed range

Defensive patterns

Strategy: validation

Validate before calling

// Reject negative/high-bit signed longs before serializing for a long field.
for (long v : values) {
  if (v < 0) {
    throw new IllegalArgumentException("long bitmap value must be non-negative: " + v);
  }
}

Prevention

Bound-check all values against [0, Long.MAX_VALUE].
Mask or fold hash outputs that can set the high bit.

When it happens

Trigger: A 64-bit bitmap holding values whose high bit is set (>= 2^63), which would be negative java longs. Usually a client treating the bitmap as unsigned 64-bit while the field is signed.

Common situations: Hashing step that produces unsigned 64-bit values with the high bit set; mixing unsigned conventions between producer and consumer.

Related errors

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