{"record":{"id":"6d5aa33ad0180cae","repo":"apache/cassandra","slug":"batch-too-large","errorCode":null,"errorMessage":"Batch too large","messagePattern":"Batch too large","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/statements/BatchStatement.java","lineNumber":452,"sourceCode":"        if (size > warnThreshold)\n        {\n            Set<String> tableNames = new HashSet<>();\n            for (IMutation mutation : mutations)\n            {\n                for (PartitionUpdate update : mutation.getPartitionUpdates())\n                    tableNames.add(update.metadata().toString());\n            }\n\n            long failThreshold = DatabaseDescriptor.getBatchSizeFailThreshold();\n\n            String format = \"Batch for {} is of size {}, exceeding specified threshold of {} by {}.{}\";\n            if (size > failThreshold)\n            {\n                Tracing.trace(format, tableNames, FBUtilities.prettyPrintMemory(size), FBUtilities.prettyPrintMemory(failThreshold),\n                              FBUtilities.prettyPrintMemory(size - failThreshold), \" (see batch_size_fail_threshold)\");\n                logger.error(format, tableNames, FBUtilities.prettyPrintMemory(size), FBUtilities.prettyPrintMemory(failThreshold),\n                             FBUtilities.prettyPrintMemory(size - failThreshold), \" (see batch_size_fail_threshold)\");\n                throw new InvalidRequestException(\"Batch too large\");\n            }\n            else if (logger.isWarnEnabled())\n            {\n                logger.warn(format, tableNames, FBUtilities.prettyPrintMemory(size), FBUtilities.prettyPrintMemory(warnThreshold),\n                            FBUtilities.prettyPrintMemory(size - warnThreshold), \"\");\n            }\n            ClientWarn.instance.warn(MessageFormatter.arrayFormat(format, new Object[] {tableNames, size, warnThreshold, size - warnThreshold, \"\"}).getMessage());\n        }\n    }\n\n    private void verifyBatchType(Collection<? extends IMutation> mutations)\n    {\n        if (!isLogged() && mutations.size() > 1)\n        {\n            Set<DecoratedKey> keySet = new HashSet<>();\n            Set<String> tableNames = new HashSet<>();\n\n            for (IMutation mutation : mutations)","sourceCodeStart":434,"sourceCodeEnd":470,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/statements/BatchStatement.java#L434-L470","documentation":"verifyBatchSize enforces the batch_size_fail_threshold guardrail: when the serialized size of a batch exceeds the fail threshold, the batch is rejected with InvalidRequestException 'Batch too large' after tracing and logging the violation. Large batches cause coordinator memory pressure and are a known anti-pattern.","triggerScenarios":"Executing (via executeWithoutConditions) a batch whose total serialized mutation size exceeds batch_size_fail_threshold_in_kb (default 50 KB, or 10000x warn threshold config); typically huge multi-partition unlogged batches or bulk-load attempts through CQL batches.","commonSituations":"Bulk imports via giant batches; time-series backfills inserting thousands of rows per batch; misconfigured thresholds after upgrading (threshold behavior changed across Cassandra versions).","solutions":["Split the batch into smaller batches or individual statements (async/parallel writes)","Raise batch_size_fail_threshold_in_kb in cassandra.yaml only if you truly understand the memory implications","Use a proper bulk-load path (COPY, sstableloader, or the bulk writer) instead of CQL batches","Reduce row/cell size being inserted per batch"],"exampleFix":"// before\n// one BEGIN BATCH with 5000 INSERTs\n// after\nfor (List<BoundStatement> chunk : partition(boundStatements, 100)) {\n    execute(BatchStatement.unlogged(chunk));\n}","handlingStrategy":"validation","validationCode":"long approxSize = statements.stream().mapToLong(Statement::getSize).sum();\nif (approxSize > batchSizeFailThresholdBytes) splitIntoSmallerBatches();","typeGuard":null,"tryCatchPattern":"catch (InvalidRequestException e) { if (e.getMessage().equals(\"Batch too large\")) { chunkAndRetryInSmallerBatches(); } else throw e; }","preventionTips":["Keep batches small (dozens of mutations, not thousands)","Use bulk-load tooling (COPY/sstableloader) for large imports","Monitor and don't casually raise batch_size_fail_threshold_in_kb"],"tags":["cql","batch","size-limit","guardrails"],"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-17T15:17:12.973Z"}