What causes "default_keyspace_rf cannot be less than 1" in apache/cassandra?

Set default_keyspace_rf to at least 1 (typically 3 for production).

apache/cassandra · error · java.lang.IllegalArgumentException

default_keyspace_rf cannot be less than 1

Error message

default_keyspace_rf cannot be less than 1

What it means

setDefaultKeyspaceRF rejects a default keyspace replication factor below 1. A default RF of 0 (or negative) is meaningless since every new keyspace would be unreadable/unwritable, so the setter throws IllegalArgumentException before any guardrail checks.

Source

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

    }

    public static void setWriteTombstoneWarnThreshold(int threshold)
    {
        validateWriteTombstoneThresholdRange(threshold, conf.min_tracked_partition_tombstone_count);
        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()
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set default_keyspace_rf to at least 1 (typically 3 for production).
Fix the templating/placeholder value in cassandra.yaml.
Guard script logic so computed RF values are clamped to >= 1 before calling the setter.

Example fix

// before
DatabaseDescriptor.setDefaultKeyspaceRF(0);
// after
DatabaseDescriptor.setDefaultKeyspaceRF(3);

Defensive patterns

Strategy: validation

Validate before calling

if (rf >= 1) DatabaseDescriptor.setDefaultKeyspaceRF(rf);

Type guard

boolean isValidDefaultRF(int rf) { return rf >= 1; }

Try / catch

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

Prevention

Use >= 3 for production defaults; never 0 as a placeholder.
Validate templated cassandra.yaml before deploy.
Clamp computed RF values to >= 1.

When it happens

Trigger: Calling DatabaseDescriptor.setDefaultKeyspaceRF(0) or a negative int, via code, JMX, or a default_keyspace_rf value in configuration that is < 1.

Common situations: Templated cassandra.yaml files with default_keyspace_rf: 0 as a placeholder; operators confusing RF 0 with 'system-managed'; scripts computing RF from node counts that yield 0.

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

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