apache/cassandra · error · IllegalArgumentException

Serialized size must not be more than 2GiB

Error message

Serialized size must not be more than 2GiB

What it means

SerializingCache stores each deserialized value as one in-memory buffer whose length must fit in an int (Java array/buffer size limit). The create() overload validates the measured value size eagerly and throws IllegalArgumentException when a single serialized value exceeds Integer.MAX_VALUE (2GiB - 1 bytes). The cache simply cannot hold an individual entry larger than 2GiB.

Source

Thrown at src/java/org/apache/cassandra/cache/SerializingCache.java:73

                   .removalListener((key, mem, cause) -> {
                       if (cause.wasEvicted()) {
                           mem.unreference();
                       }
                   })
                   .build();
    }

    public static <K, V> SerializingCache<K, V> create(long weightedCapacity, Weigher<K, RefCountedMemory> weigher, ISerializer<V> serializer)
    {
        return new SerializingCache<>(weightedCapacity, weigher, serializer);
    }

    public static <K, V> SerializingCache<K, V> create(long weightedCapacity, ISerializer<V> serializer)
    {
        return create(weightedCapacity, (key, value) -> {
            long size = value.size();
            if (size > Integer.MAX_VALUE) {
                throw new IllegalArgumentException("Serialized size must not be more than 2GiB");
            }
            return (int) size;
        }, serializer);
    }

    private V deserialize(RefCountedMemory mem)
    {
        try
        {
            return serializer.deserialize(new MemoryInputStream(mem));
        }
        catch (IOException e)
        {
            logger.trace("Cannot fetch in memory data, we will fallback to read from disk ", e);
            return null;
        }
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Ensure no single cached value exceeds 2GiB serialized; split it into smaller entries/keys.
2. Provide a custom size-measuring lambda to create() that bounds or correctly computes size and rejects oversized values earlier with a clearer message.
3. Validate value sizes before putting them into the cache.
4. Use a different storage mechanism (e.g. disk-backed store) for values larger than 2GiB.

Example fix

// before
long size = value.size();
if (size > Integer.MAX_VALUE) {
    throw new IllegalArgumentException("Serialized size must not be more than 2GiB");
}
// after
long size = value.size();
if (size > Integer.MAX_VALUE) {
    logger.warn("Skipping cache of oversized value ({} bytes); splitting or bypassing cache", size);
    return null; // handle null sizer result upstream instead of failing
}

// validate value size before caching
long size = value.size();
if (size > Integer.MAX_VALUE) {
    throw new IllegalArgumentException("Value of " + size + " bytes exceeds 2GiB cache-entry limit");
}

boolean cacheable(V v) { return v != null && v.size() <= Integer.MAX_VALUE; }

try {
    cache.put(key, value);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("2GiB")) {
        // bypass cache or split value
        storeDirectly(value);
    } else throw e;
}

When it happens

Trigger: Calling SerializingCache.create(capacity, serializer) and then putting a value whose ISelfSerializingSubject.size() (via the default sizer lambda) returns more than Integer.MAX_VALUE.

Common situations: Caching very large blobs/rows (e.g. huge collections or chunked values aggregated into one entry); a custom serializer or sizer that returns a wrong (unbounded) size; 2GiB limit hit after migrating data that grew past the int limit.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• Serialized size cannot be more than 2GiB/Integer.MAX_VALUE
• Unable to allocate %s
• Prepared statement of size %d bytes is larger than allowed m
• Cache schema version + expected + does not match current sch
• Chunk cache size cannot be changed.

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/eceed99c2429f668. Report an issue: GitHub.