{"record":{"id":"409a1f391447bbfe","repo":"apache/cassandra","slug":"system-property-was-set-to-but-must-be-1-or","errorCode":null,"errorMessage":"System property {} was set to {} but must be 1 or 2. Running with {}","messagePattern":"System property (.+?) was set to (.+?) but must be 1 or 2\\. Running with (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/locator/ReplicaPlans.java","lineNumber":102,"sourceCode":"import static org.apache.cassandra.db.ConsistencyLevel.localQuorumForOurDc;\nimport static org.apache.cassandra.locator.Replicas.addToCountPerDc;\nimport static org.apache.cassandra.locator.Replicas.countInOurDc;\nimport static org.apache.cassandra.locator.Replicas.countPerDc;\n\npublic class ReplicaPlans\n{\n    private static final Logger logger = LoggerFactory.getLogger(ReplicaPlans.class);\n\n    private static final Range<Token> FULL_TOKEN_RANGE = new Range<>(DatabaseDescriptor.getPartitioner().getMinimumToken(), DatabaseDescriptor.getPartitioner().getMinimumToken());\n\n    private static final int REQUIRED_BATCHLOG_REPLICA_COUNT\n            = Math.max(1, Math.min(2, CassandraRelevantProperties.REQUIRED_BATCHLOG_REPLICA_COUNT.getInt()));\n\n    static\n    {\n        int batchlogReplicaCount = CassandraRelevantProperties.REQUIRED_BATCHLOG_REPLICA_COUNT.getInt();\n        if (batchlogReplicaCount < 1 || 2 < batchlogReplicaCount)\n            logger.warn(\"System property {} was set to {} but must be 1 or 2. Running with {}\", CassandraRelevantProperties.REQUIRED_BATCHLOG_REPLICA_COUNT.getKey(), batchlogReplicaCount, REQUIRED_BATCHLOG_REPLICA_COUNT);\n    }\n\n    public static boolean isSufficientLiveReplicasForRead(Locator locator, AbstractReplicationStrategy replicationStrategy, ConsistencyLevel consistencyLevel, Endpoints<?> liveReplicas)\n    {\n        switch (consistencyLevel)\n        {\n            case ANY:\n                // local hint is acceptable, and local node is always live\n                return true;\n            case LOCAL_ONE:\n                return countInOurDc(liveReplicas).hasAtleast(1, 1);\n            case UNSAFE_DELAY_LOCAL_QUORUM:\n            case LOCAL_QUORUM:\n                return countInOurDc(liveReplicas).hasAtleast(localQuorumForOurDc(replicationStrategy), 1);\n            case EACH_QUORUM:\n                if (replicationStrategy instanceof NetworkTopologyStrategy)\n                {\n                    int fullCount = 0;","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/locator/ReplicaPlans.java#L84-L120","documentation":"ReplicaPlans' static initializer reads the system property cassandra.required_batchlog_replica_count, which must be 1 or 2. If the property is set outside that range, the code clamps it via Math.max(1, Math.min(2, value)) and logs this warning stating what was set, what is required, and the clamped value actually used. Batchlog writes still function, just with the clamped replica count.","triggerScenarios":"Starting Cassandra with -Dcassandra.required_batchlog_replica_count=0, 3, -1, or any integer other than 1 or 2; the clamped REQUIRED_BATCHLOG_REPLICA_COUNT constant is then used for batchlog replica decisions (e.g. consistency levels requiring batchlog replicas for hinted handoff durability).","commonSituations":"Operators copying tuning knobs from blogs with wrong values; typos (12 instead of 2); automated config tooling injecting placeholder 0; misunderstanding that only 1 or 2 are legal.","solutions":["Set the property to a legal value: -Dcassandra.required_batchlog_replica_count=1 or =2.","Remove the property entirely to use the default.","Verify the effective value in logs at startup — the warning prints the clamped value actually in effect.","Fix automated config pipelines that inject invalid values (e.g. env var defaults of 0).","Note durability trade-offs: with 1, batchlog writes tolerate fewer replicas but reduce write-ahead guarantees."],"exampleFix":"// before (jvm-server.options)\n-Dcassandra.required_batchlog_replica_count=3\n// after\n-Dcassandra.required_batchlog_replica_count=2","handlingStrategy":"validation","validationCode":"String v = System.getProperty(\"cassandra.required_batchlog_replica_count\");\nif (v != null) {\n    int i = Integer.parseInt(v.trim());\n    if (i < 1 || i > 2) throw new IllegalArgumentException(\"cassandra.required_batchlog_replica_count must be 1 or 2, got \" + i);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only set the property to 1 or 2; prefer omitting it for the default.","Validate jvm-server.options property values in config management (Puppet/Ansible) pre-deploy.","Scan startup logs for this warning as a config-drift signal.","Document the legal range where the knob is defined for your ops team."],"tags":["configuration","system-property","batchlog","validation"],"backgroundTag":"invalid-env-var-value","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}