apache/cassandra · error · RuntimeException

Failed to import sstable <filename>

Error message

Failed to import sstable <filename>

What it means

invalidateCachesForSSTable opens the sstable being imported to read its keys and evict any matching entries from the key cache/row cache. If reading the sstable's keys throws an IOException, it is rethrown as a RuntimeException naming the sstable file. This usually means the sstable is unreadable or corrupt at the point of import.

Source

Thrown at src/java/org/apache/cassandra/db/SSTableImporter.java:410

    }

    /**
     * Iterates over all keys in the sstable index and invalidates the row cache
     */
    @VisibleForTesting
    void invalidateCachesForSSTable(SSTableReader reader)
    {
        try (KeyIterator iter = reader.keyIterator())
        {
            while (iter.hasNext())
            {
                DecoratedKey decoratedKey = iter.next();
                cfs.invalidateCachedPartition(decoratedKey);
            }
        }
        catch (IOException ex)
        {
            throw new RuntimeException("Failed to import sstable " + reader.getFilename(), ex);
        }
    }

    /**
     * Verify an sstable for import, throws exception if there is a failure verifying.
     *
     * @param verifyTokens to verify that the tokens are owned by the current node
     * @param verifySSTables to verify the sstables given. If this is false a "quick" verification will be run, just deserializing metadata
     * @param extendedVerify to validate the values in the sstables
     */
    private void verifySSTableForImport(Descriptor descriptor, Set<Component> components, boolean verifyTokens, boolean verifySSTables, boolean extendedVerify)
    {
        SSTableReader reader = null;
        try
        {
            reader = SSTableReader.open(cfs, descriptor, components, cfs.metadata);
            IVerifier.Options verifierOptions = IVerifier.options()
                                                         .extendedVerification(extendedVerify)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Verify all required sstable components (-Data.db, -Index.db, -Summary.db, -Digest) are present and fully copied; re-copy the sstable set
  2. Run `nodetool scrub` or use sstableverify on the source files to check integrity; regenerate the sstable via repair/backup if corrupt
  3. Check the cause chain in the stack trace for the underlying IOException (file not found, permission, IO error)
  4. Confirm the sstable comes from a compatible Cassandra version before importing

Example fix

// before
nodetool import -- ks tbl /staging   # only ks-tbl-ka-1-Data.db present
// after
cp ks-tbl-ka-1-*.db /staging         # copy ALL components, then import
nodetool import -- ks tbl /staging
Defensive patterns

Strategy: try-catch

Validate before calling

// verify all components exist before import
for (String base : components) {
    if (!new File(dir, base).exists()) throw new IllegalStateException("Missing component: " + base);
}

Type guard

null

Try / catch

try { importer.importNewSSTables(...); } catch (RuntimeException e) { if (e.getMessage() != null && e.getMessage().startsWith("Failed to import sstable")) { log.error("Unreadable sstable", e.getCause()); /* re-copy or scrub */ } else throw e; }

Prevention

When it happens

Trigger: importNewSSTables calls invalidateCachesForSSTable on an sstable whose data/index file is truncated, unreadable due to permissions, on a failed disk, or otherwise corrupt, causing IOException while iterating decorated keys.

Common situations: Importing partially copied sstable sets (missing -Data.db or -Index.db components); sstables from a different Cassandra major version; corrupted transfer (scp/rsync interrupted); failing disk sectors.

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

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