apache/cassandra · error · IllegalArgumentException

Invalid sstable file

Error message

Invalid sstable file %s: incompatible sstable version (%s); you should have run upgradesstables before upgrading

What it means

Thrown when loading an sstable whose format version is not compatible with the running Cassandra version. Cassandra refuses to open sstables written by a much newer or incompatible release, since the on-disk layout differs. The fix is to run `upgradesstables` on the old version before upgrading the node.

Solutions

Upgrade Cassandra to a version that supports the sstable's version, or restore the sstable on a node running at least the version that wrote it
On the source cluster (old version) run `nodetool upgradesstables` before upgrading
Re-generate the data (rebuild/repair/restore via a compatible path) instead of copying incompatible files
Remove or archive the incompatible sstable file if it is not needed

Example fix

// before: directly copying new-version sstables into an older node's data dir
// after: on the source (old) cluster before upgrade
cassandra@old> nodetool upgradesstables --include-all-sstables
// then copy data files

Defensive patterns

Strategy: validation

Validate before calling

Descriptor descriptor = Descriptor.fromFilename(sstablePath);
Version v = descriptor.version; // or format.getVersion(versionString)
if (v != null && !v.isCompatible())
    throw new IllegalStateException("SSTable version " + v + " is not compatible with this node; run upgradesstables on the source cluster first");

Type guard

static boolean isCompatibleSstable(Descriptor d) { return d != null && d.version != null && d.version.isCompatible(); }

Try / catch

try {
    Descriptor d = Descriptor.fromFileWithComponent(file);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("incompatible sstable version")) {
        // route to restore-from-compatible-version / upgradesstables workflow
    } else throw e;
}

Prevention

Always run nodetool upgradesstables (or upgradesstables --include-all-sstables) before/after major version upgrades before touching data files
Only copy sstables between clusters running compatible versions; use snapshots taken on a compatible version
Avoid downgrading Cassandra in place; if unavoidable, scrub or rewrite sstables first
Document source-cluster version alongside any backup/restore artifacts

When it happens

Trigger: Calling Descriptor.fromFileWithComponent/info (e.g. via sstable tooling or loading a file) on an sstable file whose filename encodes a version string that fails Version.isCompatible() for the current binary.

Common situations: Restoring a backup written by a newer Cassandra version onto an older node; copying data files from one cluster to another running a different major version; downgrading Cassandra without scrubbing/upgrading sstables first.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/io/sstable/Descriptor.java:438

        if (!Version.validate(versionString))
            throw invalidSSTable(name, "invalid version %s", versionString);

        SSTableId id;
        try
        {
            id = SSTableIdFactory.instance.fromString(tokens.get(1));
        }
        catch (RuntimeException e)
        {
            throw invalidSSTable(name, "the 'id' part (%s) of the name doesn't parse as a valid unique identifier", tokens.get(1));
        }

        SSTableFormat<?, ?> format = formatFromName(name, tokens);
        Component component = Component.parse(tokens.get(3), format);

        Version version = format.getVersion(versionString);
        if (!version.isCompatible())
            throw invalidSSTable(name, "incompatible sstable version (%s); you should have run upgradesstables before upgrading", versionString);

        return new SSTableInfo(version, id, component);
    }

    private static class SSTableInfo
    {
        final Version version;
        final SSTableId id;
        final Component component;

        SSTableInfo(Version version, SSTableId id, Component component)
        {
            this.version = version;
            this.id = id;
            this.component = component;
        }
    }

View on GitHub (pinned to 88fd0f6a0e)