Cassandra Node Fails to Start

The Cassandra process fails to start, or starts and then exits before reaching the UN (Up/Normal) state. The cause is almost always recorded in system.log during the startup sequence, so the log is the first place to look rather than the last.

Prerequisites

Root or sudo access on the host, to read the logs and data directories and to start the service.
Confirmation that the process is actually stopped before any file is moved (systemctl status cassandra, or ps aux | grep -i cassandra). Editing or moving files under a running node's data directory produces undefined results.
For the commit log recovery below, a replication factor greater than 1, which is what makes the removal of unflushed writes recoverable from other replicas. At RF = 1 the removed writes cannot be recovered.

Symptoms

systemctl start cassandra returns, but the process is not running shortly afterwards
The process exits immediately on launch, or restarts in a loop under the service manager
nodetool status cannot connect, or the node never reaches UN
An exception or fatal error is written to system.log during startup

Diagnosis

Step 1: Read the Startup Errors

tail -200 /var/log/cassandra/system.log | grep -i "error\|exception\|fatal"

The exception class and message identify the cause directly in most cases. Read the surrounding lines for the full stack trace rather than the matched line alone.

Step 2: Check Whether a Port Is Already in Use

netstat -tlnp | grep -E "7000|9042|7199"

Port 7000 carries inter-node storage traffic, 9042 the native (CQL) transport, and 7199 JMX. A prior Cassandra process that did not exit cleanly, or another service bound to one of these ports, prevents the new process from binding.

Step 3: Check Disk Space

df -h /var/lib/cassandra

A full data or commit log volume stops the node from writing and aborts startup.

Step 4: Check File Permissions

ls -la /var/lib/cassandra/
ls -la /var/log/cassandra/

The data and log directories must be owned by the user the service runs as (cassandra on a package install). A directory left owned by root after a manual operation blocks startup.

Resolution

The cause determines the fix. Match the log pattern to the row below.

Cause	Log pattern	Solution
Port in use	`Address already in use`	Stop the process holding the port, or change the port in `cassandra.yaml`
Insufficient disk	`No space left on device`	Free disk space or add storage; see Handle Full Disk
Permission denied	`Permission denied`	Restore ownership: `chown -R cassandra:cassandra /var/lib/cassandra`
Corrupt commit log	`CommitLog` with `corrupt`	Move the corrupt segment aside, then repair (see below)
Heap allocation failure	`Could not reserve enough space`	The host has less memory available than the heap the node asks for
Schema corruption	`Schema` with `cannot`	Restore the schema from backup, or repair it from another node

Heap Allocation Failure

Could not reserve enough space means the JVM could not allocate the requested heap. On a default install the heap is computed from host memory at every start, so the computed value fits the host. The error therefore points to one of:

a pinned -Xms/-Xmx pair in an options file,
a MAX_HEAP_SIZE set in the environment or cassandra-env.sh, or
a host with less memory than the value was chosen for (for example after a downsize or on a container with a lower memory limit).

Confirm the running request and compare it against what the release computes for the host. See heap sizing per version.

Commit Log Corruption

A commit log segment that fails to replay can abort startup. Under the default commit_failure_policy: stop, a replay failure stops the node so no acknowledged write is silently lost. A truncated tail from an unclean shutdown is a separate case: the node logs the partial segment and skips it rather than stopping. The recovery below applies when replay failure is stopping the node: it removes the unreadable segment so the node can start, then restores the lost writes from replicas.

Identify the segment named in the log and the segments present on disk first:

# The exception message names the failing segment, for example CommitLog-7-1699999999999.log
grep -i "commitlog" /var/log/cassandra/system.log | grep -i "corrupt\|replay"

# Segments present on disk
ls -la /var/lib/cassandra/commitlog/

Data loss risk

Removing a commit log segment discards any writes it held that had not yet been flushed to SSTables. Perform this only when the data can be recovered from other replicas (replication factor greater than 1). With RF > 1, nodetool repair streams the missing writes back from replicas that did persist them. At RF = 1 the removed writes cannot be recovered.

Move the specific segment named in the log, not every segment, where the log identifies one. Scoping the move to the named segment discards the least unflushed data:

# Move aside only the segment named in the log
mkdir -p /tmp/corrupt_commitlog
mv /var/lib/cassandra/commitlog/CommitLog-7-1699999999999.log /tmp/corrupt_commitlog/

# Start the node
sudo systemctl start cassandra

When the failing segment cannot be identified from the log, move every segment aside as a last resort. This discards more unflushed data than the scoped move, so use it only when the named segment is unavailable:

# Last resort: move every segment aside
mkdir -p /tmp/corrupt_commitlog
mv /var/lib/cassandra/commitlog/CommitLog-*.log /tmp/corrupt_commitlog/
sudo systemctl start cassandra

Once the node reaches UN, restore the discarded writes from replicas. A commit log segment is not tied to a single table, so the set of keyspaces whose writes were lost is generally unknown; a full nodetool repair across the node is therefore the deliberate default here rather than a scoped one. Where the affected keyspace is known, scope the repair to it (nodetool repair <keyspace>) or use -pr on each node in turn to reduce the work:

# Full repair across the node (default when the affected keyspace is unknown)
nodetool repair

Repair is a heavy operation: it compares and streams data across replicas and can run for hours on a large dataset. Schedule it accordingly and expect added load on the cluster while it runs.

If the node still fails to start after a scoped move, the failing segment was misidentified or more than one segment is unreadable; re-check the log for the new segment named and repeat the move. The move itself is safe to repeat. If nodetool repair fails partway, it can be re-run: repair is idempotent in effect, and a later run re-compares the ranges the failed run did not complete.

Recovery

Confirm the node reaches UN in nodetool status.
Confirm system.log shows no repeating startup error after the fix.
If commit log segments were removed, confirm nodetool repair completed so consistency is restored from replicas.

Command	Purpose
`nodetool status`	Confirm the node reaches `UN`
`nodetool repair`	Restore consistency after removing commit log segments
`df -h /var/lib/cassandra`	Check data and commit log disk space
`netstat -tlnp`	Find a process holding a Cassandra port

Handle Full Disk - Disk space exhaustion
Recover from OOM - Node killed by the OOM killer
Connectivity Issues - Port and network reachability
Schema Disagreement - Schema version conflicts across nodes
JVM Tuning - Heap sizing per version