apache/cassandra · error · IOException

Corrupt clustering value length %d encountered, as it exceed

Error message

Corrupt clustering value length %d encountered, as it exceeds the maximum of %d, which is set via max_value_size in cassandra.yaml

What it means

validateClusteringValueLength rejects clustering value lengths exceeding DatabaseDescriptor.getMaxValueSize() (max_value_size in cassandra.yaml). A larger length cannot be legitimate, so the data is treated as corrupt and an IOException with the configured maximum in the message is thrown.

Source

Thrown at src/java/org/apache/cassandra/io/sstable/SSTableCursorReader.java:1107

        clustering.loadPart(dataReader, varLength);
        return 0;
    }

    /**
     * Rejects a clustering value length the wire cannot have produced honestly. Both checks mirror
     * AbstractType.read, the reference for this format. readUnsignedVInt32 can return a negative
     * int, which is why the first check exists: an unchecked negative length reaches
     * {@link java.io.DataInput#skipBytes} as a silent no-op, and a buffer sizer as a defect.
     *
     * <p>Every caller of this walk wraps it and reports a {@code CorruptSSTableException}.
     */
    @VisibleForTesting
    static void validateClusteringValueLength(int length) throws IOException
    {
        if (length < 0)
            throw new IOException("Corrupt (negative) clustering value length encountered: " + length);
        if (length > DatabaseDescriptor.getMaxValueSize())
            throw new IOException(String.format("Corrupt clustering value length %d encountered, as it exceeds the maximum of %d, " +
                                                "which is set via max_value_size in cassandra.yaml",
                                                length, DatabaseDescriptor.getMaxValueSize()));
    }

    private static void skipClustering(RandomAccessReader dataReader, AbstractType<?>[] types, int clusteringColumnsBound) throws IOException
    {
        long clusteringBlockHeader = 0;
        for (int clusteringIndex = 0; clusteringIndex < clusteringColumnsBound; clusteringIndex++)
        {
            // struct clustering_block {
            //    varint clustering_block_header;
            //    simple_cell[] clustering_cells;
            // };
            if (clusteringIndex % 32 == 0)
            {
                clusteringBlockHeader = dataReader.readUnsignedVInt();
            }
            // skip value if present

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Check for corruption first: nodetool verify / sstableverify, then scrub if confirmed.
Align max_value_size across all nodes' cassandra.yaml and rewrite affected sstables (scrub/compact).
Restore the sstable from backup and run nodetool repair if corruption is confirmed.
Temporarily raise max_value_size if legitimate large values were written under a larger limit.

Example fix

// before
int len = in.readInt();
readClusteringValue(in, buf, type, len);
// after
int len = in.readInt();
validateClusteringValueLength(len); // enforces max_value_size before use
readClusteringValue(in, buf, type, len);

Defensive patterns

Strategy: validation

Validate before calling

int max = DatabaseDescriptor.getMaxValueSize();
if (length < 0 || length > max)
    throw new IOException("invalid clustering length " + length + " (max " + max + ")");

Try / catch

try {
    validateClusteringValueLength(len);
} catch (IOException e) {
    throw new CorruptSSTableException(e, filename); // or align max_value_size if config-related
}

Prevention

Keep max_value_size identical on all nodes in cassandra.yaml.
Document config changes that affect previously written data.
Verify sstables when this error appears after config changes.
Scrub rather than retrying reads on the same corrupt bytes.

When it happens

Trigger: Deserializing a clustering value whose on-disk length prefix exceeds max_value_size — corrupt bytes, or a value written under a larger max_value_size now read under a smaller one.

Common situations: Corrupted sstable files; nodes with inconsistent max_value_size settings; bit corruption flipping length bytes; config changed after data was written.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

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