apache/cassandra · error · java.lang.IllegalArgumentException

default_keyspace_rf to be set (%d) cannot be greater than ma

Error message

default_keyspace_rf to be set (%d) cannot be greater than maximum_replication_factor_fail_threshold (%d)

What it means

setDefaultKeyspaceRF enforces the maximum_replication_factor_fail_threshold guardrail: when the max is not disabled (-1), the default RF cannot exceed it. The setter throws IllegalArgumentException naming both values, keeping the default keyspace RF within guardrail policy.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:5772

    {
        return conf.default_keyspace_rf;
    }

    public static void setDefaultKeyspaceRF(int value) throws IllegalArgumentException
    {
        if (value < 1)
        {
            throw new IllegalArgumentException("default_keyspace_rf cannot be less than 1");
        }

        if (value < guardrails.getMinimumReplicationFactorFailThreshold())
        {
            throw new IllegalArgumentException(String.format("default_keyspace_rf to be set (%d) cannot be less than minimum_replication_factor_fail_threshold (%d)", value, guardrails.getMinimumReplicationFactorFailThreshold()));
        }

        if (guardrails.getMaximumReplicationFactorFailThreshold() != -1 && value > guardrails.getMaximumReplicationFactorFailThreshold())
        {
            throw new IllegalArgumentException(String.format("default_keyspace_rf to be set (%d) cannot be greater than maximum_replication_factor_fail_threshold (%d)", value, guardrails.getMaximumReplicationFactorFailThreshold()));
        }

        conf.default_keyspace_rf = value;
    }


    public static boolean getUseStatementsEnabled()
    {
        return conf.use_statements_enabled;
    }

    public static void setUseStatementsEnabled(boolean enabled)
    {
        if (enabled != conf.use_statements_enabled)
        {
            logger.info("Setting use_statements_enabled to {}", enabled);
            conf.use_statements_enabled = enabled;
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Lower default_keyspace_rf to at most maximum_replication_factor_fail_threshold.
Raise maximum_replication_factor_fail_threshold via guardrails config to accommodate the desired RF.
Set maximum_replication_factor_fail_threshold to -1 (disabled) if no upper cap is wanted.

Example fix

// before
DatabaseDescriptor.setDefaultKeyspaceRF(5); // max fail threshold is 3
// after
Guardrails.setMaximumReplicationFactorFailThreshold(5);
DatabaseDescriptor.setDefaultKeyspaceRF(5);

Defensive patterns

Strategy: validation

Validate before calling

int max = DatabaseDescriptor.getGuardrails().getMaximumReplicationFactorFailThreshold(); if (max == -1 || rf <= max) DatabaseDescriptor.setDefaultKeyspaceRF(rf);

Type guard

boolean rfWithinMaxGuardrail(int rf) { int max = org.apache.cassandra.db.guardrails.Guardrails.maximumRFFailThreshold(); return max == -1 || rf <= max; }

Try / catch

try { DatabaseDescriptor.setDefaultKeyspaceRF(rf); } catch (IllegalArgumentException e) { log.error("default_keyspace_rf above guardrail max", e); }

Prevention

Check maximum_replication_factor_fail_threshold (or -1 for disabled) before setting default RF.
Raise the guardrail cap when scaling clusters.
Keep default RF and guardrails in one reviewed config change.

When it happens

Trigger: Calling setDefaultKeyspaceRF with a value greater than guardrails.getMaximumReplicationFactorFailThreshold() while that threshold != -1, e.g. setting RF 5 when maximum_replication_factor_fail_threshold is 3.

Common situations: Operators raising default RF for larger clusters after guardrails capped it; maximum_replication_factor_fail_threshold set for small clusters then reused in bigger deployments; default RF inherited from a template exceeding the cap.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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