apache/cassandra · error · java.lang.IllegalArgumentException

minimum_replication_factor_fail_threshold to be set (%d) can

Error message

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

What it means

The minimum_replication_factor guardrail's fail threshold must not exceed the cluster's default_keyspace_rf (DatabaseDescriptor.getDefaultKeyspaceRF()). A fail threshold above the default RF would mark every default-keyspace operation as failing immediately, so GuardrailsOptions.validateMinRFThreshold() throws IllegalArgumentException during config validation.

Source

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

    {
        validatePositiveNumeric(warn, Long.MAX_VALUE, name + "_warn_threshold");
        validatePositiveNumeric(fail, Long.MAX_VALUE, name + "_fail_threshold");
        validateWarnLowerThanFail(warn, fail, name);
    }

    private static void validateMinIntThreshold(int warn, int fail, String name)
    {
        validatePositiveNumeric(warn, Integer.MAX_VALUE, name + "_warn_threshold");
        validatePositiveNumeric(fail, Integer.MAX_VALUE, name + "_fail_threshold");
        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;

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Lower minimum_replication_factor_fail_threshold to a value <= default_keyspace_rf (or set it to -1 to disable).
Raise default_keyspace_rf in cassandra.yaml if the higher fail threshold is the intended policy.
Also keep minimum_replication_factor_warn_threshold >= fail threshold (MinInt threshold semantics) to clear the preceding validation.

Example fix

// before
default_keyspace_rf: 3
minimum_replication_factor_warn_threshold: 4
minimum_replication_factor_fail_threshold: 5
// after
minimum_replication_factor_fail_threshold: 3

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Always review minimum_replication_factor and default_keyspace_rf together when editing cassandra.yaml.
For min-style guardrails warn >= fail; check both orderings in your config linter.
Use -1 to disable rather than extreme values.

When it happens

Trigger: Setting minimum_replication_factor_fail_threshold (e.g. minimum_replication_factor_fail_threshold: 5) while default_keyspace_rf is lower (e.g. 3) in cassandra.yaml, or applying such a pair via live guardrail update on startup validation.

Common situations: Operators raising the min-RF fail guardrail after reducing default_keyspace_rf, or raising default_keyspace_rf expectations without aligning the two; clusters migrating from SimpleStrategy defaults (RF=1 or 3) where the guardrail was tuned for another topology.

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/4baf4e95c50678df. Report an issue: GitHub.