{"record":{"id":"28555266deb835f7","repo":"apache/cassandra","slug":"maximum-replication-factor-fail-threshold-to-be-se","errorCode":null,"errorMessage":"maximum_replication_factor_fail_threshold to be set (%d) cannot be lesser than default_keyspace_rf (%d)","messagePattern":"maximum_replication_factor_fail_threshold to be set \\((.+?)\\) cannot be lesser than default_keyspace_rf \\((.+?)\\)","errorType":"validation","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/config/GuardrailsOptions.java","lineNumber":1552,"sourceCode":"        validateWarnGreaterThanFail(warn, fail, name);\n    }\n\n    private static void validateMinRFThreshold(int warn, int fail)\n    {\n        validateMinIntThreshold(warn, fail, \"minimum_replication_factor\");\n\n        if (fail > DatabaseDescriptor.getDefaultKeyspaceRF())\n            throw new IllegalArgumentException(format(\"minimum_replication_factor_fail_threshold to be set (%d) \" +\n                                                      \"cannot be greater than default_keyspace_rf (%d)\",\n                                                      fail, DatabaseDescriptor.getDefaultKeyspaceRF()));\n    }\n\n    private static void validateMaxRFThreshold(int warn, int fail)\n    {\n        validateMaxIntThreshold(warn, fail, \"maximum_replication_factor\");\n\n        if (fail != -1 && fail < DatabaseDescriptor.getDefaultKeyspaceRF())\n            throw new IllegalArgumentException(format(\"maximum_replication_factor_fail_threshold to be set (%d) \" +\n                                                      \"cannot be lesser than default_keyspace_rf (%d)\",\n                                                      fail, DatabaseDescriptor.getDefaultKeyspaceRF()));\n    }\n\n    private static void validateMinCmsSizeThreshold(int value, String name)\n    {\n        if (value == -1)\n            return;\n\n        if (value < 3)\n            throw new IllegalArgumentException(format(\"Invalid value %d for %s: minimum allowed value is 3, \" +\n                                                      \"as CMS requires at least 3 replicas to maintain quorum safely. \" +\n                                                      \"Use -1 to disable this guardrail\", value, name));\n    }\n\n    public static void validateTimestampThreshold(DurationSpec.LongMicrosecondsBound warn,\n                                                  DurationSpec.LongMicrosecondsBound fail,\n                                                  String name)","sourceCodeStart":1534,"sourceCodeEnd":1570,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/config/GuardrailsOptions.java#L1534-L1570","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ndefault_keyspace_rf: 3\nmaximum_replication_factor_fail_threshold: 2\n// after\nmaximum_replication_factor_fail_threshold: 3","handlingStrategy":"validation","validationCode":"int fail = cfg.maximum_replication_factor_fail_threshold;\nint defaultRF = DatabaseDescriptor.getDefaultKeyspaceRF();\nif (fail != -1 && fail < defaultRF) throw new IllegalArgumentException(\"max RF fail threshold \" + fail + \" < default_keyspace_rf \" + defaultRF);","typeGuard":null,"tryCatchPattern":"try { validateGuardrailRf(cfg); } catch (IllegalArgumentException e) { log.error(\"maximum_replication_factor guardrail misconfigured: {}\", e.getMessage()); throw e; }","preventionTips":["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."],"tags":["config","guardrails","replication-factor","cassandra"],"backgroundTag":"conflicting-config-options","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}