{"record":{"id":"0db0eafc820128e7","repo":"apache/cassandra","slug":"fsreaderror-wraps-ioexception-reading-toc-file","errorCode":null,"errorMessage":"FSReadError (wraps IOException reading TOC file)","messagePattern":"FSReadError \\(wraps IOException reading TOC file\\)","errorType":"exception","errorClass":"FSReadError","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/io/sstable/format/CompressionInfoComponent.java","lineNumber":90,"sourceCode":"     * @throws FSReadError             if unable to read from TOC file.\n     */\n    public static void verifyCompressionInfoExistenceIfApplicable(Descriptor descriptor, Set<Component> actualComponents) throws CorruptSSTableException, FSReadError\n    {\n        File tocFile = descriptor.fileFor(Components.TOC);\n        if (tocFile.exists())\n        {\n            try\n            {\n                Set<Component> expectedComponents = TOCComponent.loadTOC(descriptor, false);\n                if (expectedComponents.contains(Components.COMPRESSION_INFO) && !actualComponents.contains(Components.COMPRESSION_INFO))\n                {\n                    File compressionInfoFile = descriptor.fileFor(Components.COMPRESSION_INFO);\n                    throw new CorruptSSTableException(new NoSuchFileException(compressionInfoFile.absolutePath()), compressionInfoFile);\n                }\n            }\n            catch (IOException e)\n            {\n                throw new FSReadError(e, tocFile);\n            }\n        }\n    }\n}\n","sourceCodeStart":72,"sourceCodeEnd":95,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/io/sstable/format/CompressionInfoComponent.java#L72-L95","documentation":"The same verification wraps TOC reading in a catch (IOException) and rethrows FSReadError with the TOC file attached. Any I/O failure while reading or parsing the SSTable's TOC file — not just a missing component — is surfaced as FSReadError, a fatal filesystem read error in Cassandra.","triggerScenarios":"Opening an SSTable whose TOC file cannot be read: TOC missing entirely, permission denied on the file, unreadable/corrupt TOC contents, or underlying disk I/O error during TOC load.","commonSituations":"Wrong ownership/permissions after copying SSTables as root; snapshots restored without the _toc file; NFS/EBS I/O errors; truncated TOC from unclean shutdown.","solutions":["Check the TOC file exists and is readable by the Cassandra user (ls -l, chown/chmod as needed)","Restore the TOC (and other components) from a snapshot/backup of the SSTable","Check disk/filesystem health (dmesg, filesystem errors) and Cassandra logs for the wrapped IOException cause","Remove the unreadable SSTable and let repair re-stream the data from replicas"],"exampleFix":"// before: surfacing as FSReadError obscures the cause\n// after: pre-validate TOC readability before opening the SSTable\nFile tocFile = descriptor.fileFor(Component.TOC);\nif (!tocFile.exists() || !tocFile.isReadable())\n    throw new CorruptSSTableException(new NoSuchFileException(tocFile.absolutePath()), tocFile);","handlingStrategy":"validation","validationCode":"File toc = descriptor.fileFor(Component.TOC);\nif (!Files.isReadable(toc.toPath()))\n    throw new FSReadError(new AccessDeniedException(toc.absolutePath()), toc);","typeGuard":null,"tryCatchPattern":"try { openSSTable(descriptor); }\ncatch (FSReadError e) {\n    logger.error(\"Cannot read SSTable {}: {}\", descriptor, e.getCause());\n    // check permissions/FS health, restore from snapshot or repair\n}","preventionTips":["Run Cassandra under a consistent user and fix ownership after manual copies (chown -R cassandra:cassandra)","Verify TOC presence after any restore before restarting the node","Monitor filesystem/disk errors and avoid unreliable mounts for data dirs","Gracefully shut down nodes to avoid truncated files"],"tags":["sstable","io","filesystem","toc"],"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"}