apache/cassandra · warning

Guardrail violated

Error message

Guardrail %s violated: %s

What it means

Custom guardrails (user-implemented AbstractGuardrail subclasses) report violations by decorating the message with the guardrail name and sending it to the client via ClientWarn and to tracing. This is a warning path, not an exception: the violating operation still executes but the client is notified that 'Guardrail <name> violated: <detail>'.

Solutions

1. Read the decorated message; the guardrail name and detail indicate which custom guardrail fired and why.
2. Adjust the operation to comply with the guardrail policy (e.g. reduce batch size, avoid flagged keyspace).
3. If the warning is too aggressive, reconfigure or lower the custom guardrail's threshold in cassandra.yaml or in the guardrail's implementation.
4. Check server traces (Tracing) for the redacted version if the client message was sensitive.

// Pre-check in application: run the statement against the same guardrail policy
// e.g. estimate partition/collection size before write and compare to configured guardrail warn thresholds
long approxSize = estimateMutationSize(statement);
if (approxSize > configuredGuardrailWarnThreshold) {
    log.warn("Custom guardrail '{}' would flag this operation (size={} bytes)", guardrailName, approxSize);
}

// This is a warning, not an exception: read it from client warnings
ResultSet rs = session.execute(stmt);
for (String w : rs.getExecutionInfo().getWarnings()) {
    if (w.startsWith("Guardrail " + guardrailName)) { /* adjust workload or config */ }
}

When it happens

Trigger: Any operation that triggers a custom guardrail's warn(String, String) method — i.e. the guardrail's supplier returns a non-empty warning message for the executed statement.

Common situations: Operators installing organization-specific custom guardrails that flag risky-but-legal operations (e.g. large partitions, unlogged batches on specific keyspaces); clients seeing warnings prefixed with the custom guardrail name in drivers.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• <dynamic warning, no literal in source: built by…
• 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/52b08bde42b01654. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/db/guardrails/AbstractCustomGuardrail.java:50

     * @param name                name of the custom guardrail
     * @param reason              guardrail reason
     * @param configSupplier      configuration supplier of the custom guardrail
     * @param guardWhileSuperuser when true, the guardrail will be executed even the caller is a superuser. If
     *                            false, this guardrail will be called only in case a caller is not a superuser.
     */
    public AbstractCustomGuardrail(String name, String reason, Supplier<CustomGuardrailConfig> configSupplier, boolean guardWhileSuperuser)
    {
        super(name, reason, configSupplier, guardWhileSuperuser);
    }

    @Override
    String decorateMessage(String message)
    {
        return String.format("Guardrail %s violated: %s", name, message);
    }

    @Override
    protected void warn(String message, String redactedMessage)
    {
        String msg = decorateMessage(message);
        String redactedMsg = decorateMessage(redactedMessage);

        ClientWarn.instance.warn(msg);
        Tracing.trace(redactedMsg);
        GuardrailsDiagnostics.warned(name, redactedMsg);
    }

    @Override
    protected void fail(String message, String redactedMessage, @Nullable ClientState state)
    {
        String msg = decorateMessage(message);
        String redactedMsg = decorateMessage(redactedMessage);

        ClientWarn.instance.warn(msg);
        Tracing.trace(redactedMsg);
        GuardrailsDiagnostics.failed(name, redactedMsg);

View on GitHub (pinned to 88fd0f6a0e)