{"record":{"id":"71b31254c90e51e7","repo":"apache/cassandra","slug":"failed-adding-sstables","errorCode":null,"errorMessage":"Failed adding SSTables","messagePattern":"Failed adding SSTables","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/SSTableImporter.java","lineNumber":241,"sourceCode":"        try (Refs<SSTableReader> refs = Refs.ref(newSSTables))\n        {\n            abortIfDraining();\n\n            // Validate existing SSTable-attached indexes, and then build any that are missing:\n            if (!cfs.indexManager.validateSSTableAttachedIndexes(newSSTables, false, options.validateIndexChecksum))\n                cfs.indexManager.buildSSTableAttachedIndexesBlocking(newSSTables);\n\n            cfs.getTracker().addSSTables(newSSTables);\n            for (SSTableReader reader : newSSTables)\n            {\n                if (options.invalidateCaches && cfs.isRowCacheEnabled())\n                    invalidateCachesForSSTable(reader);\n            }\n        }\n        catch (Throwable t)\n        {\n            logger.error(\"[{}] Failed adding SSTables\", importID, t);\n            throw new RuntimeException(\"Failed adding SSTables\", t);\n        }\n\n        logger.info(\"[{}] Done loading load new SSTables for {}/{}\", importID, cfs.getKeyspaceName(), cfs.getTableName());\n        return failedDirectories;\n    }\n\n    /**\n     * Check the state of this node and throws an {@link InterruptedException} if it is currently draining\n     *\n     * @throws InterruptedException if the node is draining\n     */\n    private static void abortIfDraining() throws InterruptedException\n    {\n        if (StorageService.instance.isDraining())\n            throw new InterruptedException(\"SSTables import has been aborted\");\n    }\n\n    private void logLeveling(UUID importID, Set<SSTableReader> newSSTables)","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/SSTableImporter.java#L223-L259","documentation":"After verification and moving, SSTableImporter adds the new SSTableReaders to the ColumnFamilyStore; any Throwable during that leveling step (cache load, lifecycle registration, metadata update) is logged and rethrown as RuntimeException 'Failed adding SSTables', rolling back by invalidating caches for the affected readers.","triggerScenarios":"importNewSSTables finishes moving SSTables and calls cfs.addSSTables / logLeveling; registration into the live SSTable set fails (I/O error updating metadata, cache failure, out of memory, unexpected reader state).","commonSituations":"Insufficient heap/off-heap memory for key/value caches on large imports; concurrent compaction or lifecycle operations colliding with the import; corrupted index components that pass file checks but fail on reader open.","solutions":["Inspect the wrapped cause 't' in the log to fix the root problem (memory, I/O, corrupt component)","Clean up partially added SSTables: restart the node so its SSTable list is rebuilt, verify with nodetool cfstats, and re-import","Import in smaller batches to limit cache/memory pressure","Pause concurrent operations (compactions, repairs) on the table during import"],"exampleFix":"// before: one huge import\nnodetool import -- ks table /data/import  # 2TB of sstables, OOM in addSSTables\n// after: batched import\nfor d in /data/import/batch-*; do nodetool import -- ks table \"$d\"; done","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    nodetool(\"import\", \"--\", ks, table, dir);\n} catch (RuntimeException e) {\n    logger.error(\"Import failed adding SSTables; restarting node to rebuild SSTable list\", e);\n    restartNode();\n    verifyWithCfstats(ks, table);\n}","preventionTips":["Size key/value caches and heap for the volume of imported data","Import in smaller batches rather than one massive directory","Avoid concurrent compaction/repair/lifecycle operations during import","Always read the wrapped cause ('Caused by') to find the real failure"],"tags":["sstable","import","memory","lifecycle"],"backgroundTag":"file-write-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"}