{"record":{"id":"eca31221fbede985","repo":"apache/cassandra","slug":"unsupported-commit-log-version","errorCode":null,"errorMessage":"Unsupported commit log version: ","messagePattern":"Unsupported commit log version: ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/db/commitlog/CommitLogArchiver.java","lineNumber":299,"sourceCode":"                throw new RuntimeException(\"Unable to list directory \" + dir);\n            }\n            for (File fromFile : files)\n            {\n                CommitLogDescriptor fromHeader = CommitLogDescriptor.fromHeader(fromFile, DatabaseDescriptor.getEncryptionContext());\n                CommitLogDescriptor fromName = CommitLogDescriptor.isValid(fromFile.name()) ? CommitLogDescriptor.fromFileName(fromFile.name()) : null;\n                CommitLogDescriptor descriptor;\n                if (fromHeader == null && fromName == null)\n                    throw new IllegalStateException(\"Cannot safely construct descriptor for segment, either from its name or its header: \" + fromFile.path());\n                else if (fromHeader != null && fromName != null && !fromHeader.equalsIgnoringCompression(fromName))\n                    throw new IllegalStateException(String.format(\"Cannot safely construct descriptor for segment, as name and header descriptors do not match (%s vs %s): %s\", fromHeader, fromName, fromFile.path()));\n                else if (fromName != null && fromHeader == null)\n                    throw new IllegalStateException(\"Cannot safely construct descriptor for segment, as name descriptor implies a version that should contain a header descriptor, but that descriptor could not be read: \" + fromFile.path());\n                else if (fromHeader != null)\n                    descriptor = fromHeader;\n                else descriptor = fromName;\n\n                if (descriptor.version > CommitLogDescriptor.current_version)\n                    throw new IllegalStateException(\"Unsupported commit log version: \" + descriptor.version);\n\n                if (descriptor.compression != null)\n                {\n                    try\n                    {\n                        CompressionParams.createCompressor(descriptor.compression);\n                    }\n                    catch (ConfigurationException e)\n                    {\n                        throw new IllegalStateException(\"Unknown compression\", e);\n                    }\n                }\n\n                File toFile = new File(DatabaseDescriptor.getCommitLogLocation(), descriptor.fileName());\n                if (toFile.exists())\n                {\n                    if (logger.isTraceEnabled())\n                        logger.trace(\"Skipping restore of archive {} as the segment already exists in the restore location {}\",","sourceCodeStart":281,"sourceCodeEnd":317,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/commitlog/CommitLogArchiver.java#L281-L317","documentation":"During commit log archive restore (CommitLogArchiver.maybeRestoreArchive), a descriptor is built for each archived segment from its header or file name. If the resulting descriptor's version is greater than CommitLogDescriptor.current_version, the node cannot safely read the segment, so an IllegalStateException is thrown. This guards against restoring commit logs written by a newer Cassandra version.","triggerScenarios":"Calling maybeRestoreArchive (triggered at node startup when commitlog_archiving.properties has restore directives) and an archived segment's descriptor.version exceeds CommitLogDescriptor.current_version — i.e. the segment was written by a newer Cassandra release than the running one.","commonSituations":"Downgrading a Cassandra node, restoring archived commit logs taken on a newer cluster (e.g. 5.0 segments into a 4.0 node), or pointing restore_command at a backup directory containing segments from a different major version.","solutions":["Upgrade Cassandra to a version whose CommitLogDescriptor.current_version is >= the segment's version before restoring the archive.","Remove or exclude the newer-version segments from the restore archive directory.","Verify the commitlog_archiving_properties restoreCommand/restoreDirectories point at archives from the same (or older) Cassandra version.","If downgrade is intentional, let the node start without replaying old archives and rely on backups/snapshots instead."],"exampleFix":"// before: restoring 5.0 segments into a 4.0 node -> IllegalStateException\n// after: run the target (newer) Cassandra version or filter the archive\nassert descriptor.version <= CommitLogDescriptor.current_version : \"restore archive must come from same or older Cassandra version\";","handlingStrategy":"validation","validationCode":"CommitLogDescriptor d = CommitLogDescriptor.fromFileName(segment.getName());\nif (d != null && d.version > CommitLogDescriptor.current_version)\n    throw new IllegalStateException(\"Segment \" + segment + \" written by newer Cassandra; upgrade before restore\");","typeGuard":null,"tryCatchPattern":"try { archiver.maybeRestoreArchive(); } catch (IllegalStateException e) { logger.error(\"Restore aborted: {}\", e.getMessage()); /* skip archive or upgrade */ }","preventionTips":["Only restore archives from the same or older Cassandra version","Label backup archives with the source Cassandra version","Never mix commitlog directories across versions during downgrade"],"tags":["commitlog","version-mismatch","restore"],"backgroundTag":"unsupported-version","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}