apache/cassandra · error · IllegalArgumentException

metadata cannot be null

Error message

metadata cannot be null

What it means

MmappedRegions.map(ChannelProxy, CompressionMetadata) requires a non-null compression metadata because the mmap window layout is driven by the compressed chunk index. A null CompressionMetadata means the caller has confused the compressed-file overload with the plain length-based map(channel, length, chunkSize) overload.

Solutions

1. Pass a valid CompressionMetadata created via CompressionMetadata.create(filePath) for compressed files
2. Use the length-based overload MmappedRegions.map(channel, length, chunkSize) when the file has no compression metadata
3. Add a null check / branch on metadata before calling map so uncompressed files take the plain path

Example fix

// before
CompressionMetadata metadata = descriptorMayOrMayNotBeCompressed ? null : null;
MmappedRegions regions = MmappedRegions.map(channel, metadata); // IAE: metadata cannot be null
// after
CompressionMetadata metadata = CompressionMetadata.create(channel.path());
if (metadata != null) {
    regions = MmappedRegions.map(channel, metadata);
} else {
    regions = MmappedRegions.map(channel, fileLength, chunkSize);
}

if (metadata == null) { regions = MmappedRegions.map(channel, length, chunkSize); } else { regions = MmappedRegions.map(channel, metadata); }

boolean compressed = metadata != null;

try { regions = MmappedRegions.map(channel, metadata); } catch (IllegalArgumentException e) { regions = MmappedRegions.map(channel, channel.size(), DEFAULT_CHUNK_SIZE); }

When it happens

Trigger: Calling MmappedRegions.map(channel, (CompressionMetadata) null) — typically by passing a variable that is null because the file was not compressed, or by passing the wrong field (null metadata for uncompressed sstables) into the compressed-file overload.

Common situations: Code handling both compressed and uncompressed SSTables that forget to branch: CompressionMetadata for a compressed file is obtained from CompressionMetadata.create(path); for uncompressed files it is null and the length-based map() overload must be used instead.

Related errors

• Length must be positive
• Length must not be negative
• Attempted skipBytes() on a closed RAR
• Attempted to seek in a closed RAR
• Ballot file corrupted

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

Appendix: source

Thrown at src/java/org/apache/cassandra/io/util/MmappedRegions.java:107

    {
        super(original);
        this.state = original.copy;
    }

    public static MmappedRegions empty(ChannelProxy channel)
    {
        return new MmappedRegions(new State(channel), 0, 0);
    }

    /**
     * @param channel  file to map. the MmappedRegions instance will hold shared copy of given channel.
     * @param metadata
     * @return new instance
     */
    public static MmappedRegions map(ChannelProxy channel, CompressionMetadata metadata)
    {
        if (metadata == null)
            throw new IllegalArgumentException("metadata cannot be null");
        State state = new State(channel);
        return new MmappedRegions(state, metadata);
    }

    public static MmappedRegions map(ChannelProxy channel, long length, int chunkSize)
    {
        if (length <= 0)
            throw new IllegalArgumentException("Length must be positive");
        State state = new State(channel);
        return new MmappedRegions(state, length, chunkSize);
    }

    /**
     * @return a snapshot of the memory mapped regions. The snapshot can
     * only use existing regions, it cannot create new ones.
     */
    public MmappedRegions sharedCopy()
    {

View on GitHub (pinned to 88fd0f6a0e)