{"record":{"id":"cbc9de0c152c0984","repo":"apache/cassandra","slug":"invalid-sstable-file-s-incompatible-sstable-vers","errorCode":null,"errorMessage":"Invalid sstable file %s: incompatible sstable version (%s); you should have run upgradesstables before upgrading","messagePattern":"Invalid sstable file (.+?): incompatible sstable version \\((.+?)\\); you should have run upgradesstables before upgrading","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/io/sstable/Descriptor.java","lineNumber":438,"sourceCode":"        if (!Version.validate(versionString))\n            throw invalidSSTable(name, \"invalid version %s\", versionString);\n\n        SSTableId id;\n        try\n        {\n            id = SSTableIdFactory.instance.fromString(tokens.get(1));\n        }\n        catch (RuntimeException e)\n        {\n            throw invalidSSTable(name, \"the 'id' part (%s) of the name doesn't parse as a valid unique identifier\", tokens.get(1));\n        }\n\n        SSTableFormat<?, ?> format = formatFromName(name, tokens);\n        Component component = Component.parse(tokens.get(3), format);\n\n        Version version = format.getVersion(versionString);\n        if (!version.isCompatible())\n            throw invalidSSTable(name, \"incompatible sstable version (%s); you should have run upgradesstables before upgrading\", versionString);\n\n        return new SSTableInfo(version, id, component);\n    }\n\n    private static class SSTableInfo\n    {\n        final Version version;\n        final SSTableId id;\n        final Component component;\n\n        SSTableInfo(Version version, SSTableId id, Component component)\n        {\n            this.version = version;\n            this.id = id;\n            this.component = component;\n        }\n    }\n","sourceCodeStart":420,"sourceCodeEnd":456,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/io/sstable/Descriptor.java#L420-L456","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: directly copying new-version sstables into an older node's data dir\n// after: on the source (old) cluster before upgrade\ncassandra@old> nodetool upgradesstables --include-all-sstables\n// then copy data files","handlingStrategy":"validation","validationCode":"Descriptor descriptor = Descriptor.fromFilename(sstablePath);\nVersion v = descriptor.version; // or format.getVersion(versionString)\nif (v != null && !v.isCompatible())\n    throw new IllegalStateException(\"SSTable version \" + v + \" is not compatible with this node; run upgradesstables on the source cluster first\");","typeGuard":"static boolean isCompatibleSstable(Descriptor d) { return d != null && d.version != null && d.version.isCompatible(); }","tryCatchPattern":"try {\n    Descriptor d = Descriptor.fromFileWithComponent(file);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"incompatible sstable version\")) {\n        // route to restore-from-compatible-version / upgradesstables workflow\n    } else throw e;\n}","preventionTips":["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"],"tags":["sstable","storage","version-incompatibility","upgrade"],"backgroundTag":"incompatible-source-type","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}