apache/cassandra · error · IllegalArgumentException

Length must be positive

Error message

Length must be positive

What it means

MmappedRegions.map(ChannelProxy, long length, int chunkSize) validates that the file length used to size the mmap windows is strictly positive. A length <= 0 means there are no bytes to map, so mmap windows would be meaningless and the method refuses with IllegalArgumentException.

Solutions

1. Check fileLength > 0 before calling map and skip mmap entirely for empty files
2. Re-read the file length at map time (channel.size()) rather than using a cached/stale value
3. Verify the file exists and was fully written (sync/flush completed) before mmapping
4. Fix length computations that can go negative (offset math, underflow)

Example fix

// before
long len = file.length();
MmappedRegions regions = MmappedRegions.map(channel, len, chunkSize); // throws for empty file
// after
long len = file.length();
if (len > 0) {
    regions = MmappedRegions.map(channel, len, chunkSize);
} else {
    regions = null; // nothing to map for an empty file
}

long len = channel.size(); if (len <= 0) { skipMapping(); } else { MmappedRegions.map(channel, len, chunkSize); }

boolean mappable = length > 0;

try { regions = MmappedRegions.map(channel, len, chunkSize); } catch (IllegalArgumentException e) { regions = null; }

When it happens

Trigger: Calling MmappedRegions.map(channel, length, chunkSize) with length = 0 or negative — e.g. mapping an empty or truncated file, a file whose length was read before it was fully written, or a computed length that underflowed (offset subtraction).

Common situations: Attempting to mmap a zero-byte sstable segment created by a failed/incomplete write; racing a reader against a writer that has not yet flushed any data; passing a stale or wrong file length captured before truncation.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Length must not be negative
• metadata cannot be null
• new position should not be negative
• Unable to seek to position
• A CounterId representation is exactly

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

Appendix: source

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

    }

    /**
     * @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()
    {
        return new MmappedRegions(this);
    }

    private boolean isCopy()
    {
        return copy == null;
    }

View on GitHub (pinned to 88fd0f6a0e)