Fix Cassandra Consistency Level Violation: UnavailableException

When Cassandra can't meet your consistency setting, writes or reads fail. Happens when nodes are down or replication factor is too low. Here's how to fix it fast.

You're running a Cassandra cluster, maybe a small setup with 3 nodes. You set your consistency to QUORUM for reads and writes. Then boom — you get UnavailableException: Cannot achieve consistency level. I've seen this hit a client's inventory system in the middle of a Black Friday sale. Their app just stopped writing orders.

When This Error Appears

This error pops up when Cassandra cannot meet the consistency level you asked for. Common triggers:

A node goes down unexpectedly — power outage, network blip, or someone accidentally unplugged it.
You changed the replication factor on a keyspace without restarting or running repair.
You set consistency level to ALL or EACH_QUORUM in a cluster with only 2 replicas per partition.
Your cluster is split-brained (rare in small setups, but it happens).

Root Cause in Plain English

Cassandra calculates if it has enough replicas online to satisfy your consistency level. For example, QUORUM means (replication_factor / 2) + 1 nodes must respond. If your replication factor is 3, quorum is 2 nodes. If only 1 node is up, it fails. The error is Cassandra being honest — it can't give you the guarantee you asked for.

The real issue is either the cluster has fewer live nodes than needed, or your consistency level is too strict for the cluster size.

How to Fix It — Step by Step

Step 1: Check Cluster Health

Run this command on any node:

nodetool status

Look for the status column. UN means up and normal. DN means down. If you see DN nodes, the cluster can't meet high consistency levels. Fix the down nodes first.

Step 2: Check Replication Factor per Keyspace

DESCRIBE KEYSPACE your_keyspace_name;

Look at the replication factor. If it's 3, and you have only 2 nodes alive, then QUORUM needs 2 nodes. One fails, you're stuck. The fix: either bring the third node up, or lower the consistency level in your application code.

Step 3: Lower Consistency Level (Quick Fix)

In your app config (like Spring Data Cassandra or Datastax driver), change consistency to ONE or LOCAL_ONE. This won't fail even if a node is down. Example:

// Java example
QueryOptions queryOptions = new QueryOptions();
queryOptions.setConsistencyLevel(ConsistencyLevel.ONE);
Cluster cluster = Cluster.builder()
    .addContactPoint("127.0.0.1")
    .withQueryOptions(queryOptions)
    .build();

Step 4: Bring Downed Nodes Back

If a node is down, start it again. Check logs first — maybe disk is full or Java heap is exhausted. Common fix: restart Cassandra service:

sudo service cassandra restart
# or
systemctl restart cassandra

Wait 30 seconds, then run nodetool status again. Node should show UN.

Step 5: Run Repair if You Changed Replication Factor

If you recently altered the replication factor, run repair on the keyspace:

nodetool repair -pr --full your_keyspace_name

This syncs the data across nodes. Skip this step if you didn't change replication factor — it's time-consuming.

If It Still Fails

Check your consistency level in the CQL shell. Some drivers override what you set in code. Test with:

CONSISTENCY QUORUM;
SELECT * FROM your_table WHERE partition_key = 'test';

If that works but your app fails, the driver config is wrong. Also check if you're using LOCAL_QUORUM vs QUORUM — LOCAL keeps it to one datacenter, while QUORUM includes all datacenters. Had a client last week whose app used QUORUM in a single-datacenter cluster — it's fine, but if you add a second DC later, it'll break.

Still stuck? Look at nodetool gossipinfo. If nodes report each other as down but are actually up, you got a network partition. Fix the network first, then restart all nodes.

Short version: less consistency = less failure. But load test before you go to production with QUORUM. I've seen apps crash because they set ALL and didn't know their cluster could lose a node.