{"record":{"id":"937223748265a7bb","repo":"apache/cassandra","slug":"3","errorCode":"3","errorMessage":"Unable to verify sstable files on disk","messagePattern":"Unable to verify sstable files on disk","errorType":"error_code","errorClass":"StartupException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/service/StartupChecks.java","lineNumber":1026,"sourceCode":"\n                    String name = dir.getFileName().toString();\n                    return (name.equals(Directories.SNAPSHOT_SUBDIR)\n                            || name.equals(Directories.BACKUPS_SUBDIR)\n                            || nonSSTablePaths.contains(PathUtils.toCanonicalPath(dir).toString()))\n                           ? FileVisitResult.SKIP_SUBTREE\n                           : FileVisitResult.CONTINUE;\n                }\n            };\n\n            for (String dataDir : DatabaseDescriptor.getAllDataFileLocations())\n            {\n                try\n                {\n                    Files.walkFileTree(new File(dataDir).toPath(), sstableVisitor);\n                }\n                catch (IOException e)\n                {\n                    throw new StartupException(3, \"Unable to verify sstable files on disk\", e);\n                }\n            }\n\n            if (!invalid.isEmpty())\n                throw new StartupException(StartupException.ERR_WRONG_DISK_STATE,\n                                           String.format(\"Detected unreadable sstables %s, please check \" +\n                                                         \"NEWS.txt and ensure that you have upgraded through \" +\n                                                         \"all required intermediate versions, running \" +\n                                                         \"upgradesstables\",\n                                                         Joiner.on(\",\").join(invalid)));\n\n            if (!withIllegalGenId.isEmpty())\n                throw new StartupException(StartupException.ERR_WRONG_CONFIG,\n                                           \"UUID sstable identifiers are disabled but some sstables have been \" +\n                                           \"created with UUID identifiers. You have to either delete those \" +\n                                           \"sstables or enable UUID based sstable identifers in cassandra.yaml \" +\n                                           \"(uuid_sstable_identifiers_enabled). The list of affected sstables is: \" +\n                                           Joiner.on(\", \").join(withIllegalGenId) + \". If you decide to delete sstables, \" +","sourceCodeStart":1008,"sourceCodeEnd":1044,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/service/StartupChecks.java#L1008-L1044","documentation":"During the sstable-verification startup check, Cassandra walks each data directory tree to validate sstable files on disk. If the filesystem walk itself fails (an IOException from Files.walkFileTree, e.g. I/O error or traversal failure), a StartupException with code 3 is thrown wrapping the cause. This indicates Cassandra could not even complete its scan of sstable files, not that specific files are bad.","triggerScenarios":"StartupChecks sstable check executes Files.walkFileTree(new File(dataDir).toPath(), sstableVisitor); any IOException thrown during traversal (permission errors on subdirectories, I/O errors, too many open files) is wrapped as StartupException(3, \"Unable to verify sstable files on disk\", e).","commonSituations":"Broken symlinks or subdirectory permission problems inside data dirs; underlying storage I/O failures; ulimit -n too low during deep directory walks; NFS stale handles.","solutions":["Read the wrapped cause (getCause) in the startup log to identify which path/IOException aborted the walk and fix that specific filesystem issue.","Repair directory permissions inside the data directories (chown/chmod) and clear broken symlinks.","Raise the open-file limit (ulimit -n / systemd LimitNOFILE) if the walk hit EMFILE."],"exampleFix":"# before: data sub-dir unreadable by cassandra user\nsudo chmod -R u+rwx /var/lib/cassandra/data\nsudo chown -R cassandra:cassandra /var/lib/cassandra/data\n# after: walkFileTree completes and startup proceeds","handlingStrategy":"try-catch","validationCode":"// pre-flight: ensure the walk is possible (read+execute on data tree, sane ulimit)\nfind /var/lib/cassandra/data -type d ! -readable -print   # should print nothing\nulimit -n   # should be comfortably large (e.g. 100000)","typeGuard":null,"tryCatchPattern":"try {\n    startupChecks.execute(config);\n} catch (StartupException e) {\n    if (e.getCode() == 3 && e.getCause() instanceof java.io.IOException)\n        logger.error(\"Sstable scan aborted: fix filesystem issue on data dirs\", e.getCause());\n}","preventionTips":["Keep data directories free of broken symlinks and foreign files.","Set LimitNOFILE high in the systemd unit for Cassandra.","Monitor storage health to catch I/O failures before restarts."],"tags":["startup","sstable","filesystem"],"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"}