apache/cassandra · error · java.lang.IllegalArgumentException

default_keyspace_rf to be set (%d) cannot be less than minim

Error message

default_keyspace_rf to be set (%d) cannot be less than minimum_replication_factor_fail_threshold (%d)

What it means

setDefaultKeyspaceRF also enforces the minimum_replication_factor_fail_threshold guardrail: the default RF cannot be lower than the RF at which guardrails fail operations. This keeps the default keyspace RF consistent with guardrail policy, throwing IllegalArgumentException with both values in the message.

Source

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

        logger.info("updating write_tombstone_warn_threshold to {}", threshold);
        conf.write_tombstone_warn_threshold = threshold;
    }

    public static int getDefaultKeyspaceRF()
    {
        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)
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Raise default_keyspace_rf to at least minimum_replication_factor_fail_threshold.
2. Lower minimum_replication_factor_fail_threshold (e.g. via guardrails config or Guardrails.setMinimumReplicationFactorFailThreshold) to be <= the desired default RF.
3. Align both values in cassandra.yaml so default_keyspace_rf >= minimum_replication_factor_fail_threshold.

Example fix

// before
DatabaseDescriptor.setDefaultKeyspaceRF(1); // min fail threshold is 3
// after
Guardrails.setMinimumReplicationFactorFailThreshold(1);
DatabaseDescriptor.setDefaultKeyspaceRF(1);

if (rf >= DatabaseDescriptor.getGuardrails().getMinimumReplicationFactorFailThreshold()) DatabaseDescriptor.setDefaultKeyspaceRF(rf);

boolean rfMeetsMinGuardrail(int rf) { return rf >= org.apache.cassandra.db.guardrails.Guardrails.minimumRFFailThreshold(); }

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

When it happens

Trigger: Calling setDefaultKeyspaceRF with a value below guardrails.getMinimumReplicationFactorFailThreshold(), e.g. setting RF 1 while minimum_replication_factor_fail_threshold is 2 (such as in SimpleStrategy single-node setups or dev configs).

Common situations: Dev/test clusters where operators lower the fail threshold or raise it after setting default RF; guardrails configured stricter than the default RF in cassandra.yaml; upgrading clusters where guardrails were tightened.

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

• default_keyspace_rf to be set (%d) cannot be greater than ma
• default_keyspace_rf (%d) cannot be less than minimum_replica
• Invalid guardrails configuration:
• default_keyspace_rf cannot be less than 1
• Invalid value %d for %s: maximum allowed value is %d

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