What causes "Hash of size %d encountered, expecting %d or %d" in apache/cassandra?

Verify all nodes use a Cassandra version with the same HASH_SIZE

apache/cassandra · error · IllegalStateException

Hash of size %d encountered, expecting %d or %d

Error message

Hash of size %d encountered, expecting %d or %d

What it means

When deserializing an on-heap MerkleTree leaf, the hash length is read first and must be either HASH_SIZE or 0 (empty leaf). Any other size triggers IllegalStateException('Hash of size %d encountered, expecting %d or %d'), meaning the serialized leaf is malformed or produced by an incompatible format.

Source

Thrown at src/java/org/apache/cassandra/utils/MerkleTree.java:1102

                xorOntoLeft(hash, partitionHash);

            sizeOfRange += partitionSize;
            partitionsInRange += 1;
        }

        static OnHeapLeaf deserializeWithoutIdent(DataInputPlus in) throws IOException
        {
            int size = in.readByte();
            switch (size)
            {
                case HASH_SIZE:
                    byte[] hash = new byte[HASH_SIZE];
                    in.readFully(hash);
                    return new OnHeapLeaf(hash);
                case 0:
                    return new OnHeapLeaf();
                default:
                    throw new IllegalStateException(format("Hash of size %d encountered, expecting %d or %d", size, HASH_SIZE, 0));
            }
        }

        int serializeOffHeap(ByteBuffer buffer, IPartitioner p)
        {
            if (buffer.remaining() < OffHeapLeaf.maxOffHeapSize())
                throw new IllegalStateException("Insufficient remaining bytes to deserialize a Leaf node off-heap");

            if (hash.length != HASH_SIZE)
                throw new IllegalArgumentException("Hash of unexpected size when serializing a Leaf off-heap: " + hash.length);

            final int position = buffer.position();
            buffer.put(hash);
            return ~position;
        }

        @Override
        public String toString()

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Verify all nodes use a Cassandra version with the same HASH_SIZE
Regenerate the MerkleTree by rerunning repair validation
Check the reported size value against corruption/truncation of the stream
Re-serialize from source data rather than re-reading the damaged payload

Defensive patterns

Strategy: try-catch

Try / catch

try {
    leaf = OnHeapLeaf.deserializeWithoutIdent(in);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Hash of size")) {
        logger.error("Malformed leaf hash length in tree stream: {}", e.getMessage());
        // treat tree as corrupt; request re-validation from the source node
    }
    throw e;
}

Prevention

Match Cassandra versions across nodes (HASH_SIZE must agree)
Do not hand-edit or transform serialized MerkleTree payloads
Keep a single read path for the tree stream to avoid position desync
Re-serialize from data instead of re-reading damaged payloads

When it happens

Trigger: Reading an on-heap leaf whose length byte is neither 0 nor the fixed HASH_SIZE — corrupt stream, wrong read position, or a tree written with a different hash size.

Common situations: Repair streaming across Cassandra versions where the tree hash size changed; reading a corrupted or hand-modified MerkleTree payload; desynced deserialization of the tree stream.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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