apache/cassandra · error · MutationExceededMaxSizeException

MutationExceededMaxSizeException

Error message

MutationExceededMaxSizeException

What it means

Mutation.validateSize checks that the serialized mutation plus overhead does not exceed MAX_MUTATION_SIZE (the maximum a single commit-log segment/mutation may hold). Oversized mutations are counted in the commit-log oversizedMutations metric and rejected with MutationExceededMaxSizeException, since they cannot be written atomically to the commit log.

Source

Thrown at src/java/org/apache/cassandra/db/Mutation.java:219

    @Override
    public Supplier<Mutation> hintOnFailure()
    {
        return this;
    }

    @Override
    public Mutation get()
    {
        return this;
    }

    public void validateSize(int version, int overhead)
    {
        long totalSize = serializedSize(version) + overhead;
        if(totalSize > MAX_MUTATION_SIZE)
        {
            CommitLog.instance.metrics.oversizedMutations.mark();
            throw new MutationExceededMaxSizeException(this, version, totalSize);
        }
    }

    public PartitionUpdate getPartitionUpdate(TableMetadata table)
    {
        return table == null ? null : modifications.get(table.id);
    }

    public boolean isEmpty()
    {
        return modifications.isEmpty();
    }

    /**
     * Creates a new mutation that merges all the provided mutations.
     *
     * @param mutations the mutations to merge together. All mutation must be
     * on the same keyspace and partition key. There should also be at least one

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Split the write into smaller mutations/batches (keep batches under a few dozen partitions).
2. Increase commitlog_segment_size_in_mb if genuinely large mutations are required (careful: affects GC and disk).
3. Reduce cell/row sizes (compress large blobs, chunk wide rows) before writing.
4. Watch commitlog metrics.oversizedMutations to find offending clients.

Example fix

// before
BatchStatement batch = new BatchStatement();
for (Row r : millionRows) batch.add(insert.bind(r)); // one huge mutation
session.execute(batch);
// after
for (List<Row> chunk : partition(millionRows, 100)) {
    BatchStatement batch = new BatchStatement();
    chunk.forEach(r -> batch.add(insert.bind(r)));
    session.execute(batch);
}

long estSize = mutations.stream().mapToLong(m -> m.serializedSize(MESSAGES_VERSION)).sum() + OVERHEAD;
if (estSize > MAX_MUTATION_SIZE) splitAndSendInChunks();

try { session.execute(batch); } catch (MutationExceededMaxSizeException | InvalidQueryException e) { splitBatchAndRetry(); }

When it happens

Trigger: A single Mutation whose serialized partitions exceed MAX_MUTATION_SIZE (default derived from commitlog_segment_size_in_mb, ~1/2 segment, min 64MB cap): very large batches, huge partition updates, or repair mutations created by createRepairMutation for very large ranges.

Common situations: Oversized unlogged/logged batches in application code; backfill jobs writing extremely wide rows in one mutation; hints or repair replay exceeding the limit after segment size was lowered.

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

• Missing required directive CommitLogSync
• Batch sync specified, but commitlog_sync_period found.
• Missing value for commitlog_sync_group_window.
• Group sync specified, but commitlog_sync_period found. Only
• Missing value for commitlog_sync_period.

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