apache/cassandra · critical · FSReadError

FSReadError (wraps IOException reading TOC file)

Error message

FSReadError (wraps IOException reading TOC file)

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/io/sstable/format/CompressionInfoComponent.java:90

     * @throws FSReadError             if unable to read from TOC file.
     */
    public static void verifyCompressionInfoExistenceIfApplicable(Descriptor descriptor, Set<Component> actualComponents) throws CorruptSSTableException, FSReadError
    {
        File tocFile = descriptor.fileFor(Components.TOC);
        if (tocFile.exists())
        {
            try
            {
                Set<Component> expectedComponents = TOCComponent.loadTOC(descriptor, false);
                if (expectedComponents.contains(Components.COMPRESSION_INFO) && !actualComponents.contains(Components.COMPRESSION_INFO))
                {
                    File compressionInfoFile = descriptor.fileFor(Components.COMPRESSION_INFO);
                    throw new CorruptSSTableException(new NoSuchFileException(compressionInfoFile.absolutePath()), compressionInfoFile);
                }
            }
            catch (IOException e)
            {
                throw new FSReadError(e, tocFile);
            }
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Check the TOC file exists and is readable by the Cassandra user (ls -l, chown/chmod as needed)
2. Restore the TOC (and other components) from a snapshot/backup of the SSTable
3. Check disk/filesystem health (dmesg, filesystem errors) and Cassandra logs for the wrapped IOException cause
4. Remove the unreadable SSTable and let repair re-stream the data from replicas

Example fix

// before: surfacing as FSReadError obscures the cause
// after: pre-validate TOC readability before opening the SSTable
File tocFile = descriptor.fileFor(Component.TOC);
if (!tocFile.exists() || !tocFile.isReadable())
    throw new CorruptSSTableException(new NoSuchFileException(tocFile.absolutePath()), tocFile);

File toc = descriptor.fileFor(Component.TOC);
if (!Files.isReadable(toc.toPath()))
    throw new FSReadError(new AccessDeniedException(toc.absolutePath()), toc);

try { openSSTable(descriptor); }
catch (FSReadError e) {
    logger.error("Cannot read SSTable {}: {}", descriptor, e.getCause());
    // check permissions/FS health, restore from snapshot or repair
}

When it happens

Trigger: 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.

Common situations: Wrong ownership/permissions after copying SSTables as root; snapshots restored without the _toc file; NFS/EBS I/O errors; truncated TOC from unclean shutdown.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Exception occurred while writing to
• Failed importing SSTables
• Corrupt flags value for clustering prefix (isStatic flag set
• Corrupted sstable. Invalid flags found deserializing Deletio
• Failed to import sstable <filename>

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