{"record":{"id":"1df3200b93cc77bb","repo":"apache/cassandra","slug":"batch-for-is-of-size-exceeding-specified-th","errorCode":null,"errorMessage":"Batch for {} is of size {}, exceeding specified threshold of {} by {}.{}","messagePattern":"Batch for (.+?) is of size (.+?), exceeding specified threshold of (.+?) by (.+?)\\.(.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/cql3/statements/BatchStatement.java","lineNumber":459,"sourceCode":"            }\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)\n            {\n                for (PartitionUpdate update : mutation.getPartitionUpdates())\n                {\n                    keySet.add(update.partitionKey());\n\n                    tableNames.add(update.metadata().toString());\n                }","sourceCodeStart":441,"sourceCodeEnd":477,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/statements/BatchStatement.java#L441-L477","documentation":"BatchStatement.verifyBatchSize rejects/flags a batch whose serialized mutation size exceeds batch_size_warn_threshold_in_kb (and batch_size_fail_threshold_in_kb for hard failure). The warning includes the actual size, the configured threshold, and the overage, and also warns the client via ClientWarn.","triggerScenarios":"executeWithoutConditions -> verifyBatchSize: a LOGGED/UNLOGGED batch's total mutations size exceeds the warn threshold; logged path is warn-only, exceeding the fail threshold throws a QueryException.","commonSituations":"Batches inserting thousands of rows or huge blobs; application using batches as an ETL bulk-load mechanism (anti-pattern); low thresholds after tuning changes.","solutions":["Split the oversized batch into smaller batches under the threshold","Use UNLOGGED batches limited to a single partition, or better, non-batch inserts / concurrent writers for bulk loads","Raise batch_size_warn_threshold_in_kb / batch_size_fail_threshold_in_kb in cassandra.yaml only after confirming the workload is intentional"],"exampleFix":"// before\n// single batch with 5,000 inserts\n// after\nfor (List<BoundStatement> chunk : Lists.partition(statements, 100)) {\n    batch statements in chunk; execute;\n}","handlingStrategy":"validation","validationCode":"// Client-side size guard before executing a batch\nfunction assertBatchSizeWithinLimit(statements, maxBytes = 4096 * 1024) {\n  const approx = statements.reduce((n, s) => n + JSON.stringify(s.getValues ? s.getValues() : s).length, 0);\n  if (approx > maxBytes) throw new Error('batch too large: ' + approx + ' bytes; split it');\n}","typeGuard":null,"tryCatchPattern":"try {\n  session.execute(batch);\n} catch (InvalidQueryException e) {\n  if (String.valueOf(e).contains(\"batch\") && String.valueOf(e).contains(\"exceed\")) {\n    splitAndRetryInChunks(batch); // chunk size < warn threshold\n  } else throw e;\n}","preventionTips":["Keep batches small (ideally single-partition UNLOGGED)","Never use batches for bulk loading; use concurrent single-statement inserts","Chunk multi-row writes client-side under batch_size_warn_threshold_in_kb"],"tags":["batch","payload-size","anti-pattern","threshold"],"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"}