{"record":{"id":"85d4e8f9dcd76180","repo":"apache/cassandra","slug":"mutationexceededmaxsizeexception","errorCode":null,"errorMessage":"MutationExceededMaxSizeException","messagePattern":"MutationExceededMaxSizeException","errorType":"exception","errorClass":"MutationExceededMaxSizeException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/Mutation.java","lineNumber":219,"sourceCode":"    @Override\n    public Supplier<Mutation> hintOnFailure()\n    {\n        return this;\n    }\n\n    @Override\n    public Mutation get()\n    {\n        return this;\n    }\n\n    public void validateSize(int version, int overhead)\n    {\n        long totalSize = serializedSize(version) + overhead;\n        if(totalSize > MAX_MUTATION_SIZE)\n        {\n            CommitLog.instance.metrics.oversizedMutations.mark();\n            throw new MutationExceededMaxSizeException(this, version, totalSize);\n        }\n    }\n\n    public PartitionUpdate getPartitionUpdate(TableMetadata table)\n    {\n        return table == null ? null : modifications.get(table.id);\n    }\n\n    public boolean isEmpty()\n    {\n        return modifications.isEmpty();\n    }\n\n    /**\n     * Creates a new mutation that merges all the provided mutations.\n     *\n     * @param mutations the mutations to merge together. All mutation must be\n     * on the same keyspace and partition key. There should also be at least one","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/Mutation.java#L201-L237","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Split the write into smaller mutations/batches (keep batches under a few dozen partitions).","Increase commitlog_segment_size_in_mb if genuinely large mutations are required (careful: affects GC and disk).","Reduce cell/row sizes (compress large blobs, chunk wide rows) before writing.","Watch commitlog metrics.oversizedMutations to find offending clients."],"exampleFix":"// before\nBatchStatement batch = new BatchStatement();\nfor (Row r : millionRows) batch.add(insert.bind(r)); // one huge mutation\nsession.execute(batch);\n// after\nfor (List<Row> chunk : partition(millionRows, 100)) {\n    BatchStatement batch = new BatchStatement();\n    chunk.forEach(r -> batch.add(insert.bind(r)));\n    session.execute(batch);\n}","handlingStrategy":"validation","validationCode":"long estSize = mutations.stream().mapToLong(m -> m.serializedSize(MESSAGES_VERSION)).sum() + OVERHEAD;\nif (estSize > MAX_MUTATION_SIZE) splitAndSendInChunks();","typeGuard":null,"tryCatchPattern":"try { session.execute(batch); } catch (MutationExceededMaxSizeException | InvalidQueryException e) { splitBatchAndRetry(); }","preventionTips":["Keep batches small (< a few hundred KB, tens of partitions).","Chunk backfill/wide-row writes into bounded mutations.","Monitor commitlog oversizedMutations metric to catch offenders early."],"tags":["mutation","commitlog","payload-too-large","batch"],"backgroundTag":"payload-too-large","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}