## TL;DR
The new cassandra version cannot read sstables written by the much older version: you skipped a version whose sstable format changed. Run nodetool upgradesstables to rewrite them in the new format, or if the jump is too far, step through the intermediate version first. Check logs for the exact format incompatibility before choosing.

## The query

```text
cassandra error: sstable migration failed - incompatible version after upgrade
```

## Use this when

- cassandra sstable migration failed after upgrade
- Incompatible sstable version errors on node start
- Skipped cassandra versions and now sstables will not load
- An agent upgraded cassandra across a format boundary

## Not for

- Gossip or seed-node problems (check the network and seeds)
- Repair or compaction failures (different subsystem)
- Client driver version mismatches (check the driver)

## Steps

### 1. Confirm the incompatibility in the logs

```bash
grep -i "sstable" /var/log/cassandra/system.log | tail -30
```

Expected output: lines naming the sstable version found versus the version expected. This confirms the failure is a format gap, not corruption.

### 2. Check the upgrade path you took

Compare the old and new versions against the project's upgrade notes. Cassandra supports skipping some versions but not all: a format change between them requires an intermediate stop.

Expected output: the answer to "did I skip a required intermediate version". If yes, the intermediate version is the fix, not a flag.

### 3. Case A: the versions are adjacent enough - upgrade the sstables

```bash
nodetool upgradesstables
```

Run on each node, one at a time, watching disk space: the rewrite temporarily needs room for both formats. Expected output: sstables rewritten to the current format, and the errors stop on restart.

### 4. Case B: you skipped a format boundary - step through the intermediate version

Downgrade (or install) the intermediate version, let it start and upgrade the sstables in its format, then upgrade to the target version and run upgradesstables again.

Expected output: each step's sstables load cleanly, because no step crosses more than one format boundary.

### 5. Verify the cluster is healthy

```bash
nodetool status
nodetool tpstats
```

Expected output: all nodes up and participating, no sstable errors in the logs. Run a repair on the upgraded keyspaces to confirm data integrity.

## Tool compatibility

apache cassandra 4.x and 5.x. upgradesstables and the version-gating behavior are the same.

## Variant phrasings

### cassandra sstable migration failed incompatible version

Steps 1 through 3: confirm in logs, then upgradesstables.

### cassandra cannot read old sstables after upgrade

Step 4 when the version jump crossed a format boundary: step through the intermediate version.

### nodetool upgradesstables when to run

Step 3: after any upgrade that changes the sstable format, one node at a time.

## Why it happens

SSTables are versioned binary files, and major versions change the format. Cassandra refuses to read a format it does not understand rather than misreading data, and upgradesstables exists to rewrite old files into the new format. Skipping a version can skip the only code that knew how to read your files, which is why the project documents which jumps are allowed.

## Edge cases

- upgradesstables rewrites every sstable: on large nodes it takes hours and doubles disk usage transiently. Watch disk and run off-peak.
- Rolling back after upgrading sstables is not possible: the old version cannot read the new format. Snapshot before you start.
- Mixed-version clusters during the procedure are normal but temporary: finish every node before declaring victory.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gUxBA-eM5-PQG4e0y_pyIQ