{"record":{"id":"d965ed688e5e7102","repo":"apache/cassandra","slug":"cannot-safely-construct-descriptor-for-segment-as-d965ed","errorCode":null,"errorMessage":"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: ","messagePattern":"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: ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/commitlog/CommitLogArchiver.java","lineNumber":293,"sourceCode":"\n        for (String dir : restoreDirectories.split(DELIMITER))\n        {\n            File[] files = new File(dir).tryList();\n            if (files == null)\n            {\n                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                }","sourceCodeStart":275,"sourceCodeEnd":311,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/commitlog/CommitLogArchiver.java#L275-L311","documentation":"Thrown by maybeRestoreArchive() when a segment's filename implies a commit log descriptor version that must carry a header, but the header cannot be read (fromName != null but fromHeader == null). The file is truncated below the header size, unreadable, or its header is unrecoverable, so restore aborts.","triggerScenarios":"A restore-directory file has a valid modern-format name but CommitLogDescriptor.fromHeader returns null because the file is truncated (smaller than the descriptor header), empty, or the header bytes are unreadable/corrupt.","commonSituations":"Interrupted copy of an archived segment (partial file); 0-byte placeholder files; disk corruption at the start of the segment; rsync/scp interrupted mid-transfer.","solutions":["Re-copy the truncated segment from the archive and verify its size against the original.","Delete 0-byte or partial files that are incomplete copies (the real segment remains in the archive).","Check archive-side integrity (checksums) before restoring segments.","Ensure the storage holding restore directories has no silent truncation (full disks, failed mounts)."],"exampleFix":"// before: partially copied segment (header missing)\nls -l /mnt/restore/CommitLog-4-00000.log  # 12 bytes\n// after: re-copy fully and verify size\ncp /archive/CommitLog-4-00000.log /mnt/restore/ && cmp /archive/CommitLog-4-00000.log /mnt/restore/CommitLog-4-00000.log","handlingStrategy":"validation","validationCode":"for (File f : restoreDir.listFiles()) {\n    CommitLogDescriptor n = CommitLogDescriptor.isValid(f.getName()) ? CommitLogDescriptor.fromFileName(f.getName()) : null;\n    if (n != null && CommitLogDescriptor.fromHeader(f, DatabaseDescriptor.getEncryptionContext()) == null)\n        log.warn(\"Segment too small/truncated to read header, re-copy: \" + f);\n}","typeGuard":null,"tryCatchPattern":"try { archiver.maybeRestoreArchive(); }\ncatch (IllegalStateException e) {\n    if (e.getMessage().contains(\"header descriptor could not be read\"))\n        log.error(\"Segment truncated/incomplete; re-copy full segment from archive\", e);\n    throw e;\n}","preventionTips":["Verify copied segment sizes/checksums against the archive before startup","Guard archive copies against interruption (use atomic rename after full copy)","Delete 0-byte partial files left by failed transfers"],"tags":["cassandra","commitlog","restore","corruption"],"backgroundTag":"file-read-failed","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"}