{"record":{"id":"29602f27ae9c0c76","repo":"apache/cassandra","slug":"failed-to-create-a-key-iterator-for-sstable-file","errorCode":null,"errorMessage":"Failed to create a key iterator for sstable ${filename}","messagePattern":"Failed to create a key iterator for sstable (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/io/sstable/ReducingKeyIterator.java","lineNumber":53,"sourceCode":" */\npublic class ReducingKeyIterator implements CloseableIterator<DecoratedKey>\n{\n    private final ArrayList<KeyIterator> iters;\n    private volatile IMergeIterator<DecoratedKey, DecoratedKey> mi;\n\n    public ReducingKeyIterator(Collection<SSTableReader> sstables)\n    {\n        iters = new ArrayList<>(sstables.size());\n        for (SSTableReader sstable : sstables)\n        {\n            try\n            {\n                iters.add(sstable.keyIterator());\n            }\n            catch (IOException ex)\n            {\n                iters.forEach(FileUtils::closeQuietly);\n                throw new RuntimeException(\"Failed to create a key iterator for sstable \" + sstable.getFilename());\n            }\n        }\n    }\n\n    private void maybeInit()\n    {\n        if (mi != null)\n            return;\n\n        synchronized (this)\n        {\n            if (mi == null)\n            {\n                mi = MergeIterator.get(iters, DecoratedKey.comparator, new MergeIterator.Reducer<DecoratedKey, DecoratedKey>()\n                {\n                    DecoratedKey reduced = null;\n\n                    @Override","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/io/sstable/ReducingKeyIterator.java#L35-L71","documentation":"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.","triggerScenarios":"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.","commonSituations":"Compaction, scrub, or index builds racing with an sstable deleted by cleanup; corrupted sstable files; wrong permissions after restoring backups; filesystem I/O errors.","solutions":["Check the sstable file named in the message exists and is readable; run sstableverify / nodetool verify.","Run nodetool scrub or sstablescrub on the affected keyspace/table to repair or quarantine the corrupt sstable.","Restore the missing/corrupt file from backup or run nodetool repair to rebuild data.","If it raced with cleanup, retry the operation and avoid concurrent compaction/cleanup deleting sstables mid-read.","Check filesystem health (dmesg/system logs) and fix underlying disk problems."],"exampleFix":"// before\nthrow new RuntimeException(\"Failed to create a key iterator for sstable \" + sstable.getFilename());\n// after\nthrow new RuntimeException(\"Failed to create a key iterator for sstable \" + sstable.getFilename(), ex); // keep cause","handlingStrategy":"try-catch","validationCode":"File dataFile = new File(sstable.getFilename());\nif (!dataFile.exists() || !dataFile.canRead())\n    throw new IllegalStateException(\"sstable unreadable: \" + dataFile);","typeGuard":null,"tryCatchPattern":"try {\n    new ReducingKeyIterator(sstables);\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"Failed to create a key iterator\")) {\n        // exclude the named sstable and retry, or schedule scrub\n    }\n}","preventionTips":["Run nodetool verify regularly to catch unreadable sstables early.","Avoid deleting/moving sstables while compaction or index builds run.","Keep backups of sstable files before maintenance operations.","Check file permissions after restoring from backups."],"tags":["io","sstable","compaction"],"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"}