apache/cassandra · critical · SyncException

SyncException (wraps IOException from disk writer flush/sync

Error message

SyncException (wraps IOException from disk writer flush/sync; explicitly reported to the user)

What it means

SSTableSimpleUnsortedWriter.maybeSync() periodically flushes and fsyncs the SSTable writer's data to disk. If the sync throws an IOException, it is wrapped in SyncException (a RuntimeException) so it can propagate out of add()/addColumn code that does not declare IOException, explicitly surfacing the disk write failure to the user.

Source

Thrown at src/java/org/apache/cassandra/io/sstable/SSTableSimpleUnsortedWriter.java:130

        // and the maintaining of the bufferSize is in general not perfect. This has always been the case for this class but we should
        // improve that. In particular, what we count is closer to the serialized value, but it's debatable that it's the right thing
        // to count since it will take a lot more space in memory and the bufferSize is first and foremost used to avoid OOM when
        // using this writer.
        currentSize += UnfilteredSerializer.serializer.serializedSize(row, helper, 0, format.getLatestVersion().correspondingMessagingVersion());
    }

    private void maybeSync() throws SyncException
    {
        try
        {
            if (currentSize > maxSStableSizeInBytes)
                sync();
        }
        catch (IOException e)
        {
            // addColumn does not throw IOException but we want to report this to the user,
            // so wrap it in a temporary RuntimeException that we'll catch in rawAddRow above.
            throw new SyncException(e);
        }
    }

    private PartitionUpdate.Builder createPartitionUpdateBuilder(DecoratedKey key)
    {
        return new PartitionUpdate.Builder(metadata.get(), key, columns, 4)
        {
            @Override
            public void add(Row row)
            {
                super.add(row);
                countRow(row);
                maybeSync();
            }
        };
    }

    @Override

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Free disk space or provision more storage on the data directory filesystem
2. Check system logs (dmesg) for I/O errors and fix/replace failing disks or mounts
3. Retry the bulk load after resolving the storage issue; delete partial output sstables first
4. Wrap writer usage (add/close) in try-with-resources and handle SyncException by aborting and restarting the load cleanly

Example fix

// before
writer.addRow(key, values);
// after
try {
    writer.addRow(key, values);
} catch (SyncException e) {
    // disk flush/sync failed: check disk space/health, then restart the bulk load
    throw new IllegalStateException("SSTable write sync failed: " + e.getCause(), e);
}

// check writable space before bulk loading
java.io.File dataDir = new File(outputDir);
if (dataDir.getUsableSpace() < requiredBytes) {
    throw new IllegalStateException("insufficient disk space for sstable writer");
}
if (!dataDir.canWrite()) throw new IllegalStateException("data dir not writable");

try (SSTableSimpleUnsortedWriter writer = createWriter(...)) {
    writer.addRow(key, values);
} catch (SyncException e) {
    // flush/sync failed: log cause (IOException), check disk, restart load
    throw new IllegalStateException("SSTable sync failed: " + e.getCause(), e);
}

When it happens

Trigger: Calling add(...) on an SSTableSimpleUnsortedWriter when the internal buffer threshold triggers sync() and the underlying disk writer's flush/sync throws IOException — disk full, I/O error, or filesystem failure during sstable write.

Common situations: Running out of disk space during bulk loads (e.g. sstableloader or custom bulk writers); failing disks during heavy write load; filesystem quotas or read-only mounts; exporting data with CQLSSTableWriter on storage with I/O problems.

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

• FSWriteError (wraps IOException writing sstable component)
• Failed to save Bloom filter for SSTable:
• Failed to save index summary to
• Corrupt flags value for clustering prefix (isStatic flag set
• Corrupted sstable. Invalid flags found deserializing Deletio

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