apache/cassandra · error · RuntimeException

Failed to create a key iterator for sstable ${filename}

Error message

Failed to create a key iterator for sstable ${filename}

What it means

ReducingKeyIterator merges key iterators from multiple SSTables. When opening an individual sstable's key iterator fails with an IOException, the constructor closes all already-created iterators and rethrows as a RuntimeException naming the sstable file. It identifies which sstable could not be read.

Source

Thrown at src/java/org/apache/cassandra/io/sstable/ReducingKeyIterator.java:53

 */
public class ReducingKeyIterator implements CloseableIterator<DecoratedKey>
{
    private final ArrayList<KeyIterator> iters;
    private volatile IMergeIterator<DecoratedKey, DecoratedKey> mi;

    public ReducingKeyIterator(Collection<SSTableReader> sstables)
    {
        iters = new ArrayList<>(sstables.size());
        for (SSTableReader sstable : sstables)
        {
            try
            {
                iters.add(sstable.keyIterator());
            }
            catch (IOException ex)
            {
                iters.forEach(FileUtils::closeQuietly);
                throw new RuntimeException("Failed to create a key iterator for sstable " + sstable.getFilename());
            }
        }
    }

    private void maybeInit()
    {
        if (mi != null)
            return;

        synchronized (this)
        {
            if (mi == null)
            {
                mi = MergeIterator.get(iters, DecoratedKey.comparator, new MergeIterator.Reducer<DecoratedKey, DecoratedKey>()
                {
                    DecoratedKey reduced = null;

                    @Override

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Check the sstable file named in the message exists and is readable; run sstableverify / nodetool verify.
2. Run nodetool scrub or sstablescrub on the affected keyspace/table to repair or quarantine the corrupt sstable.
3. Restore the missing/corrupt file from backup or run nodetool repair to rebuild data.
4. If it raced with cleanup, retry the operation and avoid concurrent compaction/cleanup deleting sstables mid-read.
5. Check filesystem health (dmesg/system logs) and fix underlying disk problems.

Example fix

// before
throw new RuntimeException("Failed to create a key iterator for sstable " + sstable.getFilename());
// after
throw new RuntimeException("Failed to create a key iterator for sstable " + sstable.getFilename(), ex); // keep cause

File dataFile = new File(sstable.getFilename());
if (!dataFile.exists() || !dataFile.canRead())
    throw new IllegalStateException("sstable unreadable: " + dataFile);

try {
    new ReducingKeyIterator(sstables);
} catch (RuntimeException e) {
    if (e.getMessage().contains("Failed to create a key iterator")) {
        // exclude the named sstable and retry, or schedule scrub
    }
}

When it happens

Trigger: Constructing a ReducingKeyIterator over SSTableReader instances where sstable.keyIterator() throws IOException for one sstable — missing/corrupt data or index file, unreadable permissions, or the sstable deleted/moved between listing and iteration.

Common situations: Compaction, scrub, or index builds racing with an sstable deleted by cleanup; corrupted sstable files; wrong permissions after restoring backups; filesystem I/O errors.

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

• Corrupt flags value for clustering prefix (isStatic flag set
• Corrupted sstable. Invalid flags found deserializing Deletio
• Failed importing SSTables
• Failed to import sstable <filename>
• Throwing new Runtime to bypass exception handler when disk i

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