{"record":{"id":"22e61485fcd4fffe","repo":"apache/cassandra","slug":"exception-occurred-while-writing-to","errorCode":null,"errorMessage":"Exception occurred while writing to ","messagePattern":"Exception occurred while writing to ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/io/sstable/format/TOCComponent.java","lineNumber":111,"sourceCode":"    public static void updateTOC(Descriptor descriptor, Collection<Component> components)\n    {\n        if (components.isEmpty())\n            return;\n\n        File tocFile = descriptor.fileFor(Components.TOC);\n\n        Set<String> componentNames = new TreeSet<>(Collections2.transform(components, Component::name));\n\n        if (tocFile.exists())\n            componentNames.addAll(FileUtils.readLines(tocFile));\n\n        try\n        {\n            FileUtils.write(tocFile, new ArrayList<>(componentNames), CREATE, TRUNCATE_EXISTING, SYNC);\n        }\n        catch (RuntimeException ex)\n        {\n            throw new RuntimeException(\"Exception occurred while writing to \" + tocFile,\n                                       ex.getCause() != null ? ex.getCause() : ex);\n        }\n    }\n\n    /**\n     * Loads existing TOC file or creates a new one.\n     *\n     * @param descriptor descriptor to load TOC for\n     * @return set of loaded or discovered components\n     * @throws IOError when loading of a component is erroneous\n     * @throws FSWriteError when creating of a new TOC file is erroneous\n     */\n    public static Set<Component> loadOrCreate(Descriptor descriptor)\n    {\n        try\n        {\n            return TOCComponent.loadTOC(descriptor);\n        }","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/io/sstable/format/TOCComponent.java#L93-L129","documentation":"TOCComponent.updateTOC rewrites the TableOfContents.txt component listing all files of an SSTable. If writing fails with a RuntimeException, it rethrows it wrapped in 'Exception occurred while writing to <tocFile>', surfacing the underlying cause. A missing/outdated TOC makes the SSTable invisible or partially loadable on restart.","triggerScenarios":"rewriteTOC during scrub/upgradesstables/repair flows when the filesystem write fails: read-only mount, disk full, permission denied on the SSTable directory, or I/O error during create/truncate/sync of the TOC file.","commonSituations":"Disk full during heavy compaction/scrub; incorrect ownership/permissions on the data directory (e.g. after restoring files as root); read-only filesystem after OS remount; exhausted inodes.","solutions":["Free disk space and retry the operation (df -h on the data volume).","Fix permissions/ownership on the SSTable directory so the Cassandra user can write (chown -R cassandra:cassandra /var/lib/cassandra).","Check the filesystem isn't mounted read-only (mount | grep) and remount rw.","Inspect the wrapped cause in the exception — it names the actual I/O failure.","Recreate the TOC manually if needed, then restart the node."],"exampleFix":"// before: data dir owned by root, scrub fails\nls -l /var/lib/cassandra/data/keyspace1  # owner root\n// after\nchown -R cassandra:cassandra /var/lib/cassandra/data/keyspace1\nnodetool scrub keyspace1","handlingStrategy":"try-catch","validationCode":"// Java: precheck writability of the sstable directory\nFile dir = tocFile.getParentFile();\nif (!dir.canWrite()) throw new IllegalStateException(\"Data dir not writable: \" + dir);","typeGuard":null,"tryCatchPattern":"try {\n    toc.rewriteTOC(...);\n} catch (RuntimeException e) {\n    logger.error(\"TOC write failed for {}: cause={}\", tocFile, e.getCause(), e);\n    alertDiskFullOrPermissions(tocFile);\n}","preventionTips":["Keep >20% free space on data volumes; alert on disk-full thresholds","Run Cassandra as its own user and never chown data dirs to root","Monitor mounts for read-only remounts","Inspect e.getCause() — the wrapper hides the real I/O error"],"tags":["sstable","toc","filesystem","io"],"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"}