apache/cassandra · error · UnavailableException

Cannot achieve consistency level %s for batchlog in local DC

Error message

Cannot achieve consistency level %s for batchlog in local DC, required:2, available:0

What it means

Batchlog writes require at least REQUIRED_BATCHLOG_REPLICA_COUNT (2) live batchlog endpoints in the local datacenter to meet the batchlog consistency level. When no suitable live endpoints exist in the local DC, ReplicaPlans throws this UnavailableException immediately rather than letting the write time out, telling you the CL cannot be achieved (required:2, available:0).

Source

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

        //  - choose min(2, number of qualifying candiates above)
        //  - allow the local node to be the only replica only if it's a single-node DC
        Collection<InetAddressAndPort> chosenEndpoints = filterBatchlogEndpoints(false,
                                                                                 local.rack,
                                                                                 localEndpoints,
                                                                                 Collections::shuffle,
                                                                                 (r) -> FailureDetector.isEndpointAlive.test(r) && metadata.directory.peerState(r) == NodeState.JOINED,
                                                                                 ThreadLocalRandom.current()::nextInt);

        // Batchlog is hosted by either one node or two nodes from different racks.
        ConsistencyLevel consistencyLevel = chosenEndpoints.size() == 1 ? ConsistencyLevel.ONE : ConsistencyLevel.TWO;

        if (chosenEndpoints.isEmpty())
        {
            if (isAny)
                chosenEndpoints = Collections.singleton(FBUtilities.getBroadcastAddressAndPort());
            else
                // UnavailableException instead of letting the batchlog write unnecessarily timeout
                throw new UnavailableException("Cannot achieve consistency level " + consistencyLevel
                        + " for batchlog in local DC, required:" + REQUIRED_BATCHLOG_REPLICA_COUNT
                        + ", available:" + 0,
                        consistencyLevel, REQUIRED_BATCHLOG_REPLICA_COUNT, 0);
        }

        return ReplicaLayout.forTokenWrite(Keyspace.open(SchemaConstants.SYSTEM_KEYSPACE_NAME).getReplicationStrategy(),
                                           SystemReplicas.getSystemReplicas(chosenEndpoints).forToken(token),
                                           EndpointsForToken.empty(token));
    }

    public static ReplicaPlan.ForWrite forBatchlogWrite(ClusterMetadata metadata, boolean isAny) throws UnavailableException
    {
        // A single case we write not for range or token, but multiple mutations to many tokens
        Token token = DatabaseDescriptor.getPartitioner().getMinimumToken();
        Keyspace systemKeyspace = Keyspace.open(SchemaConstants.SYSTEM_KEYSPACE_NAME);

        ReplicaLayout.ForTokenWrite liveAndDown = liveAndDownForBatchlogWrite(token, metadata, isAny);
        // Batchlog is hosted by either one node or two nodes from different racks.

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Ensure at least 2 nodes are live in the local datacenter, or add nodes
Use unlogged batches only if safe, or reduce batch usage
Check node status with nodetool status and restore failed nodes/network connectivity

Defensive patterns

Strategy: try-catch

Validate before calling

int liveInLocalDc = tokenMetadata.getSnapshot().getEndpoints(localDc).size();
if (liveInLocalDc < 2) throw new IllegalStateException("Need >=2 live nodes in local DC for batchlog writes");

Try / catch

try { session.execute(batchStatement); }
catch (UnavailableException e) { if (e.getMessage().contains("batchlog")) { /* back off and retry after nodes recover */ } }

Prevention

Keep at least 2 (ideally 3) nodes per DC that store the system keyspace
Monitor per-DC live node counts and alert before batchlog writes become impossible
Prefer unlogged batches or atomic batches where the batchlog is not required

When it happens

Trigger: Executing a logged batch (or any operation needing a batchlog write) when fewer than 2 batchlog-suitable replicas are alive in the local DC, e.g. with a single-node DC or after mass node failure/outage.

Common situations: Running a single-node cluster or 1-node DC while writing logged batches; nodes in the local DC down during a rolling upgrade; network partition isolating the local DC.

Related errors

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