apache/cassandra · warning · Threshold

<dynamic warning, no literal in source: built by…

Error message

<dynamic warning, no literal in source: built by Guardrail.warn via Threshold.errMsg -> ErrorMessageProvider.createMessage(isWarning, what, value, thresholdValue), delivered to the client via ClientWarn>

What it means

Threshold guardrails (e.g. partition_size_in_kb, collection_size_in_kb, query page size) emit a dynamic warning when a measured value exceeds the configured 'warn' threshold but stays below the 'fail' threshold. The message is built by the threshold's ErrorMessageProvider and delivered to the client via ClientWarn; the operation still succeeds.

Solutions

1. Reduce the offending value: split large partitions, trim collections, or cap batch/IN sizes in the application.
2. If the warning threshold is too strict for your workload, raise it via cassandra.yaml or the corresponding guardrails config table and reload config.
3. Treat the warning as an early signal before the 'fail' threshold starts rejecting writes; migrate data model proactively.

Example fix

// before: unbounded partition growth triggers threshold warning
INSERT INTO sensor_data (sensor_id, ts, value) ... // millions of rows per sensor
// after: bucket the partition by time to stay under the threshold
INSERT INTO sensor_data (sensor_id, day, ts, value) VALUES (?, toUnixTimestamp(now()) bucketed, ...);

// Before writing, estimate the guarded metric, e.g. partition size:
long partitionBytes = estimatePartitionSize(key);
long warnThresholdKb = readGuardrailWarnThreshold("partition_size_in_kb");
if (partitionBytes / 1024 > warnThresholdKb) {
    log.warn("Write will exceed partition size guardrail warn threshold");
}

// Non-fatal: consume client warnings
ResultSet rs = session.execute(stmt);
rs.getExecutionInfo().getWarnings().forEach(w -> {
    if (w.contains("exceeds warn threshold")) {
        // reduce partition/collection size or raise threshold
    }
});

When it happens

Trigger: Executing a statement whose measured value (e.g. partition size, number of rows in a collection, IN clause size) exceeds the corresponding guardrail's warn threshold in cassandra.yaml.

Common situations: Writing very large partitions or huge collections; unbounded row growth over time pushing a table past the warning threshold; after enabling guardrails on an existing cluster with already-oversized data.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Guardrail violated
• Aggregation query used on multiple partition keys (IN…
• Aggregation query used without partition key
• Cannot alter gc_grace_seconds of a materialized view to 0…
• Client driver , version is below recommended minimum version

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

Appendix: source

Thrown at src/java/org/apache/cassandra/db/guardrails/Threshold.java:157

            triggerFail(value, failValue, what, containsUserData, state);
            return;
        }

        long warnValue = warnValue(state);
        if (compare(value, warnValue))
            triggerWarn(value, warnValue, what, containsUserData);
    }

    private void triggerFail(long value, long failValue, String what, boolean containsUserData, ClientState state)
    {
        String fullMessage = errMsg(false, what, value, failValue);
        fail(fullMessage, containsUserData ? redactedErrMsg(false, value, failValue) : fullMessage, state);
    }

    private void triggerWarn(long value, long warnValue, String what, boolean containsUserData)
    {
        String fullMessage = errMsg(true, what, value, warnValue);
        warn(fullMessage, containsUserData ? redactedErrMsg(true, value, warnValue) : fullMessage);
    }

    /**
     * A function used to build the error message of a triggered {@link Threshold} guardrail.
     */
    interface ErrorMessageProvider
    {
        /**
         * Called when the guardrail is triggered to build the corresponding error message.
         *
         * @param isWarning Whether the trigger is a warning one; otherwise it is a failure one.
         * @param what      A string, provided by the call to the {@link #guard} method, describing what the guardrail
         *                  has been applied to (and that has triggered it).
         * @param value     The value that triggered the guardrail (as a string).
         * @param threshold The threshold that was passed to trigger the guardrail (as a string).
         */
        String createMessage(boolean isWarning, String what, String value, String threshold);
    }

View on GitHub (pinned to 88fd0f6a0e)