apache/cassandra · warning

Batch for is of size , exceeding specified threshold of by .

Error message

Batch for {} is of size {}, exceeding specified threshold of {} by {}.{}

What it means

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.

Solutions

1. Split the oversized batch into smaller batches under the threshold
2. Use UNLOGGED batches limited to a single partition, or better, non-batch inserts / concurrent writers for bulk loads
3. Raise batch_size_warn_threshold_in_kb / batch_size_fail_threshold_in_kb in cassandra.yaml only after confirming the workload is intentional

Example fix

// before
// single batch with 5,000 inserts
// after
for (List<BoundStatement> chunk : Lists.partition(statements, 100)) {
    batch statements in chunk; execute;
}

// Client-side size guard before executing a batch
function assertBatchSizeWithinLimit(statements, maxBytes = 4096 * 1024) {
  const approx = statements.reduce((n, s) => n + JSON.stringify(s.getValues ? s.getValues() : s).length, 0);
  if (approx > maxBytes) throw new Error('batch too large: ' + approx + ' bytes; split it');
}

try {
  session.execute(batch);
} catch (InvalidQueryException e) {
  if (String.valueOf(e).contains("batch") && String.valueOf(e).contains("exceed")) {
    splitAndRetryInChunks(batch); // chunk size < warn threshold
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: Batches inserting thousands of rows or huge blobs; application using batches as an ETL bulk-load mechanism (anti-pattern); low thresholds after tuning changes.

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

• Batch too large
• Batch with conditions cannot span multiple partitions
• Batch with conditions cannot span multiple tables
• Cannot include a counter statement in a logged batch
• Cannot include a virtual table statement in a logged batch

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/statements/BatchStatement.java:459

            }

            long failThreshold = DatabaseDescriptor.getBatchSizeFailThreshold();

            String format = "Batch for {} is of size {}, exceeding specified threshold of {} by {}.{}";
            if (size > failThreshold)
            {
                Tracing.trace(format, tableNames, FBUtilities.prettyPrintMemory(size), FBUtilities.prettyPrintMemory(failThreshold),
                              FBUtilities.prettyPrintMemory(size - failThreshold), " (see batch_size_fail_threshold)");
                logger.error(format, tableNames, FBUtilities.prettyPrintMemory(size), FBUtilities.prettyPrintMemory(failThreshold),
                             FBUtilities.prettyPrintMemory(size - failThreshold), " (see batch_size_fail_threshold)");
                throw new InvalidRequestException("Batch too large");
            }
            else if (logger.isWarnEnabled())
            {
                logger.warn(format, tableNames, FBUtilities.prettyPrintMemory(size), FBUtilities.prettyPrintMemory(warnThreshold),
                            FBUtilities.prettyPrintMemory(size - warnThreshold), "");
            }
            ClientWarn.instance.warn(MessageFormatter.arrayFormat(format, new Object[] {tableNames, size, warnThreshold, size - warnThreshold, ""}).getMessage());
        }
    }

    private void verifyBatchType(Collection<? extends IMutation> mutations)
    {
        if (!isLogged() && mutations.size() > 1)
        {
            Set<DecoratedKey> keySet = new HashSet<>();
            Set<String> tableNames = new HashSet<>();

            for (IMutation mutation : mutations)
            {
                for (PartitionUpdate update : mutation.getPartitionUpdates())
                {
                    keySet.add(update.partitionKey());

                    tableNames.add(update.metadata().toString());
                }

View on GitHub (pinned to 88fd0f6a0e)