apache/cassandra · error · java.lang.IllegalArgumentException

Invalid value %d for %s: minimum allowed value is 3, as CMS

Error message

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

What it means

The CMS (Cluster Metadata Service) size guardrail thresholds must be at least 3, because CMS requires at least 3 replicas to maintain quorum safely. Values of 0, 1, or 2 are rejected by validateMinCmsSizeThreshold(); -1 (disable) is explicitly allowed.

Source

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

    }

    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)
    {
        // this function is used for both upper and lower thresholds because lower threshold is relative
        // despite using MinThreshold we still want the warn threshold to be less than or equal to
        // the fail threshold.
        validateMaxLongThreshold(warn == null ? -1 : warn.toMicroseconds(),
                                 fail == null ? -1 : fail.toMicroseconds(),
                                 name);
    }

    private static void validateWarnLowerThanFail(long warn, long fail, String name)
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set the threshold to 3 or higher.
Use -1 if you intend to disable this guardrail (not 0).
If a script generates the value, clamp it: Math.max(3, requested) unless requested == -1.

Example fix

// before
cms_size_guardrail_threshold: 1
// after
cms_size_guardrail_threshold: 3
// or to disable
cms_size_guardrail_threshold: -1

Defensive patterns

Strategy: validation

Validate before calling

int v = cmsSizeThreshold;
if (v != -1 && v < 3) throw new IllegalArgumentException("CMS size guardrail must be >= 3 or -1 to disable, got " + v);

Try / catch

try { applyCmsGuardrail(v); } catch (IllegalArgumentException e) { log.error("CMS guardrail value invalid: {}", e.getMessage()); throw e; }

Prevention

Do not use 0 to disable this guardrail; the disable sentinel is -1.
Clamp generated values to >= 3 unless they are -1.
Document quorum rationale (CMS needs >= 3 replicas) in your config templates.

When it happens

Trigger: Setting a CMS-related guardrail threshold (e.g. cms_new_nodes_before_cleanup-related minimum thresholds, validateMinCmsSizeThreshold callers) to 0, 1 or 2 in cassandra.yaml or through a live config update.

Common situations: Operators setting the threshold to 0 or 1 thinking 0 means 'disabled' (for this guardrail disable is -1); single-node dev clusters being configured with CMS guardrail sizes of 1 and then copied to shared configs.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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