What causes "Failed to deserialize bitmap from bytes." in apache/flink?

Inspect the attached cause (e) in the DeserializationException — RoaringBitmap's exception tells you whether it is a cookie mismatch, truncation, or garbage input.

apache/flink · error · DeserializationException

Failed to deserialize bitmap from bytes.

Error message

Failed to deserialize bitmap from bytes.

What it means

Thrown by RoaringBitmapData.fromBytes(byte[]) when the underlying RoaringBitmap library fails to deserialize the given byte array. The bytes are wrapped in a ByteBuffer and handed to RoaringBitmap.deserialize; any exception (bad cookie/version, truncated array, non-roaring data) is rethrown as a DeserializationException with this message and the original cause attached.

Source

Thrown at flink-core/src/main/java/org/apache/flink/types/bitmap/RoaringBitmapData.java:69

    }

    // ~ Static Methods ----------------------------------------------------------------

    public static RoaringBitmapData empty() {
        return new RoaringBitmapData();
    }

    public static RoaringBitmapData from(@Nonnull Bitmap other) {
        return new RoaringBitmapData(toRoaringBitmapData(other));
    }

    public static RoaringBitmapData fromBytes(@Nonnull byte[] bytes)
            throws DeserializationException {
        RoaringBitmapData rb32 = new RoaringBitmapData();
        try {
            rb32.roaringBitmap.deserialize(ByteBuffer.wrap(bytes));
        } catch (Exception e) {
            throw new DeserializationException("Failed to deserialize bitmap from bytes.", e);
        }
        return rb32;
    }

    public static RoaringBitmapData fromArray(@Nonnull int[] values) {
        RoaringBitmapData rb32 = new RoaringBitmapData();
        rb32.roaringBitmap.add(values);
        return rb32;
    }

    public static RoaringBitmapData toRoaringBitmapData(Bitmap bm) throws IllegalArgumentException {
        if (!(bm instanceof RoaringBitmapData)) {
            throw new IllegalArgumentException("Unsupported bitmap type: " + bm.getClass() + ".");
        }
        return (RoaringBitmapData) bm;
    }

    // ~ Bitmap Interface Implementations ------------------------------------------------

View on GitHub (pinned to 2f3c205e92)

Solutions

Inspect the attached cause (e) in the DeserializationException — RoaringBitmap's exception tells you whether it is a cookie mismatch, truncation, or garbage input.
Verify the byte array was produced by RoaringBitmap.serialize()/RoaringBitmapData serialization on the same RoaringBitmap version on both ends; align versions in pom.xml if they differ.
Check for truncation: log bytes.length and compare with the size recorded when the bitmap was written (roaring serialized size is available before writing).
If the data may come from other bitmap types, deserialize via the type tag your writer stored instead of assuming RoaringBitmapData.

Example fix

// before
RoaringBitmapData bitmap = RoaringBitmapData.fromBytes(bytes);

// after
RoaringBitmapData bitmap;
try {
    bitmap = RoaringBitmapData.fromBytes(bytes);
} catch (DeserializationException e) {
    throw new IllegalStateException("Corrupt bitmap payload (" + bytes.length + " bytes)", e.getCause());
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    RoaringBitmapData rb = RoaringBitmapData.fromBytes(bytes);
} catch (DeserializationException e) {
    // inspect e.getCause(): cookie mismatch => version skew; IBRunOverrun/truncated => corrupt payload
    log.error("Bitmap payload unreadable ({} bytes)", bytes.length, e.getCause());
    throw e;
}

Prevention

Pin the same RoaringBitmap dependency version on writer and reader sides.
Store the byte length alongside the payload and verify before deserializing.
Round-trip test serialization of every bitmap type you persist.

When it happens

Trigger: Calling RoaringBitmapData.fromBytes(bytes) with bytes that are not a complete serialized RoaringBitmap: truncated arrays, arrays produced by a different bitmap library or format, corrupted state, or bytes serialized with an incompatible RoaringBitmap version whose serialized cookie/layout differs.

Common situations: Reading bitmap state back from a store (DB BLOB, Kafka message, checkpoint/saved state) where the writer used a different serializer or RoaringBitmap version; network truncation; accidentally passing raw user bitset bytes instead of roaring-serialized bytes.

Related errors

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/7613aa7d2fc45781. Report an issue: GitHub.