apache/cassandra · error · RuntimeException

Exception occurred while writing to

Error message

Exception occurred while writing to 

What it means

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.

Source

Thrown at src/java/org/apache/cassandra/io/sstable/format/TOCComponent.java:111

    public static void updateTOC(Descriptor descriptor, Collection<Component> components)
    {
        if (components.isEmpty())
            return;

        File tocFile = descriptor.fileFor(Components.TOC);

        Set<String> componentNames = new TreeSet<>(Collections2.transform(components, Component::name));

        if (tocFile.exists())
            componentNames.addAll(FileUtils.readLines(tocFile));

        try
        {
            FileUtils.write(tocFile, new ArrayList<>(componentNames), CREATE, TRUNCATE_EXISTING, SYNC);
        }
        catch (RuntimeException ex)
        {
            throw new RuntimeException("Exception occurred while writing to " + tocFile,
                                       ex.getCause() != null ? ex.getCause() : ex);
        }
    }

    /**
     * Loads existing TOC file or creates a new one.
     *
     * @param descriptor descriptor to load TOC for
     * @return set of loaded or discovered components
     * @throws IOError when loading of a component is erroneous
     * @throws FSWriteError when creating of a new TOC file is erroneous
     */
    public static Set<Component> loadOrCreate(Descriptor descriptor)
    {
        try
        {
            return TOCComponent.loadTOC(descriptor);
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Free disk space and retry the operation (df -h on the data volume).
2. Fix permissions/ownership on the SSTable directory so the Cassandra user can write (chown -R cassandra:cassandra /var/lib/cassandra).
3. Check the filesystem isn't mounted read-only (mount | grep) and remount rw.
4. Inspect the wrapped cause in the exception — it names the actual I/O failure.
5. Recreate the TOC manually if needed, then restart the node.

Example fix

// before: data dir owned by root, scrub fails
ls -l /var/lib/cassandra/data/keyspace1  # owner root
// after
chown -R cassandra:cassandra /var/lib/cassandra/data/keyspace1
nodetool scrub keyspace1

// Java: precheck writability of the sstable directory
File dir = tocFile.getParentFile();
if (!dir.canWrite()) throw new IllegalStateException("Data dir not writable: " + dir);

try {
    toc.rewriteTOC(...);
} catch (RuntimeException e) {
    logger.error("TOC write failed for {}: cause={}", tocFile, e.getCause(), e);
    alertDiskFullOrPermissions(tocFile);
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• FSReadError (wraps IOException reading TOC file)
• Failed importing SSTables
• Corrupt flags value for clustering prefix (isStatic flag set
• Corrupted sstable. Invalid flags found deserializing Deletio
• Failed to import sstable <filename>

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