apache/cassandra · error · java.lang.IllegalArgumentException

maximum_replication_factor_fail_threshold to be set (%d) can

Error message

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

What it means

The maximum_replication_factor guardrail's fail threshold cannot be below the cluster's default_keyspace_rf (when not disabled, i.e. != -1). Otherwise every default keyspace would breach the max-RF guardrail, so validateMaxRFThreshold() throws IllegalArgumentException.

Source

Thrown at src/java/org/apache/cassandra/config/GuardrailsOptions.java:1552

        validateWarnGreaterThanFail(warn, fail, name);
    }

    private static void validateMinRFThreshold(int warn, int fail)
    {
        validateMinIntThreshold(warn, fail, "minimum_replication_factor");

        if (fail > DatabaseDescriptor.getDefaultKeyspaceRF())
            throw new IllegalArgumentException(format("minimum_replication_factor_fail_threshold to be set (%d) " +
                                                      "cannot be greater than default_keyspace_rf (%d)",
                                                      fail, DatabaseDescriptor.getDefaultKeyspaceRF()));
    }

    private static void validateMaxRFThreshold(int warn, int fail)
    {
        validateMaxIntThreshold(warn, fail, "maximum_replication_factor");

        if (fail != -1 && fail < DatabaseDescriptor.getDefaultKeyspaceRF())
            throw new IllegalArgumentException(format("maximum_replication_factor_fail_threshold to be set (%d) " +
                                                      "cannot be lesser than default_keyspace_rf (%d)",
                                                      fail, DatabaseDescriptor.getDefaultKeyspaceRF()));
    }

    private static void validateMinCmsSizeThreshold(int value, String name)
    {
        if (value == -1)
            return;

        if (value < 3)
            throw new IllegalArgumentException(format("Invalid value %d for %s: minimum allowed value is 3, " +
                                                      "as CMS requires at least 3 replicas to maintain quorum safely. " +
                                                      "Use -1 to disable this guardrail", value, name));
    }

    public static void validateTimestampThreshold(DurationSpec.LongMicrosecondsBound warn,
                                                  DurationSpec.LongMicrosecondsBound fail,
                                                  String name)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Raise maximum_replication_factor_fail_threshold to >= default_keyspace_rf.
Set maximum_replication_factor_fail_threshold to -1 to disable the fail threshold (explicitly allowed by the != -1 check).
Lower default_keyspace_rf if the tighter max-RF cap is the intended policy.

Example fix

// before
default_keyspace_rf: 3
maximum_replication_factor_fail_threshold: 2
// after
maximum_replication_factor_fail_threshold: 3

Defensive patterns

Strategy: validation

Validate before calling

int fail = cfg.maximum_replication_factor_fail_threshold;
int defaultRF = DatabaseDescriptor.getDefaultKeyspaceRF();
if (fail != -1 && fail < defaultRF) throw new IllegalArgumentException("max RF fail threshold " + fail + " < default_keyspace_rf " + defaultRF);

Try / catch

try { validateGuardrailRf(cfg); } catch (IllegalArgumentException e) { log.error("maximum_replication_factor guardrail misconfigured: {}", e.getMessage()); throw e; }

Prevention

When raising default_keyspace_rf, re-check maximum_replication_factor thresholds.
Set fail threshold to -1 to disable the cap instead of a too-low value.
Keep a config test that starts Cassandra with your yaml in CI.

When it happens

Trigger: Setting maximum_replication_factor_fail_threshold lower than default_keyspace_rf (e.g. fail threshold 2 with default_keyspace_rf 3) in cassandra.yaml or via a live guardrail config update; also triggered whenever default_keyspace_rf is later raised above the fail threshold since validation runs at startup/update.

Common situations: Operators lowering the max-RF guardrail to block large keyspaces but forgetting their own default RF; raising default_keyspace_rf (e.g. 1 to 3) during topology changes without revisiting the max-RF fail threshold.

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/28555266deb835f7. Report an issue: GitHub.