apache/cassandra · warning

System property was set to but must be 1 or 2. Running with

Error message

System property {} was set to {} but must be 1 or 2. Running with {}

What it means

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.

Solutions

1. Set the property to a legal value: -Dcassandra.required_batchlog_replica_count=1 or =2.
2. Remove the property entirely to use the default.
3. Verify the effective value in logs at startup — the warning prints the clamped value actually in effect.
4. Fix automated config pipelines that inject invalid values (e.g. env var defaults of 0).
5. Note durability trade-offs: with 1, batchlog writes tolerate fewer replicas but reduce write-ahead guarantees.

Example fix

// before (jvm-server.options)
-Dcassandra.required_batchlog_replica_count=3
// after
-Dcassandra.required_batchlog_replica_count=2

String v = System.getProperty("cassandra.required_batchlog_replica_count");
if (v != null) {
    int i = Integer.parseInt(v.trim());
    if (i < 1 || i > 2) throw new IllegalArgumentException("cassandra.required_batchlog_replica_count must be 1 or 2, got " + i);
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• Cannot mix auto and manual DC weights
• Cannot set concurrent_validations greater than…
• Cannot set repair_session_max_tree_depth to which is < 10…
• Cannot set source data center to be local data center, when…
• Cassandra system property flag

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

Appendix: source

Thrown at src/java/org/apache/cassandra/locator/ReplicaPlans.java:102

import static org.apache.cassandra.db.ConsistencyLevel.localQuorumForOurDc;
import static org.apache.cassandra.locator.Replicas.addToCountPerDc;
import static org.apache.cassandra.locator.Replicas.countInOurDc;
import static org.apache.cassandra.locator.Replicas.countPerDc;

public class ReplicaPlans
{
    private static final Logger logger = LoggerFactory.getLogger(ReplicaPlans.class);

    private static final Range<Token> FULL_TOKEN_RANGE = new Range<>(DatabaseDescriptor.getPartitioner().getMinimumToken(), DatabaseDescriptor.getPartitioner().getMinimumToken());

    private static final int REQUIRED_BATCHLOG_REPLICA_COUNT
            = Math.max(1, Math.min(2, CassandraRelevantProperties.REQUIRED_BATCHLOG_REPLICA_COUNT.getInt()));

    static
    {
        int batchlogReplicaCount = CassandraRelevantProperties.REQUIRED_BATCHLOG_REPLICA_COUNT.getInt();
        if (batchlogReplicaCount < 1 || 2 < batchlogReplicaCount)
            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);
    }

    public static boolean isSufficientLiveReplicasForRead(Locator locator, AbstractReplicationStrategy replicationStrategy, ConsistencyLevel consistencyLevel, Endpoints<?> liveReplicas)
    {
        switch (consistencyLevel)
        {
            case ANY:
                // local hint is acceptable, and local node is always live
                return true;
            case LOCAL_ONE:
                return countInOurDc(liveReplicas).hasAtleast(1, 1);
            case UNSAFE_DELAY_LOCAL_QUORUM:
            case LOCAL_QUORUM:
                return countInOurDc(liveReplicas).hasAtleast(localQuorumForOurDc(replicationStrategy), 1);
            case EACH_QUORUM:
                if (replicationStrategy instanceof NetworkTopologyStrategy)
                {
                    int fullCount = 0;

View on GitHub (pinned to 88fd0f6a0e)