{"record":{"id":"ec892c0b10660e6d","repo":"apache/cassandra","slug":"syncexception-wraps-ioexception-from-disk-writer","errorCode":null,"errorMessage":"SyncException (wraps IOException from disk writer flush/sync; explicitly reported to the user)","messagePattern":"SyncException \\(wraps IOException from disk writer flush/sync; explicitly reported to the user\\)","errorType":"exception","errorClass":"SyncException","httpStatus":null,"severity":"critical","filePath":"src/java/org/apache/cassandra/io/sstable/SSTableSimpleUnsortedWriter.java","lineNumber":130,"sourceCode":"        // and the maintaining of the bufferSize is in general not perfect. This has always been the case for this class but we should\n        // improve that. In particular, what we count is closer to the serialized value, but it's debatable that it's the right thing\n        // to count since it will take a lot more space in memory and the bufferSize is first and foremost used to avoid OOM when\n        // using this writer.\n        currentSize += UnfilteredSerializer.serializer.serializedSize(row, helper, 0, format.getLatestVersion().correspondingMessagingVersion());\n    }\n\n    private void maybeSync() throws SyncException\n    {\n        try\n        {\n            if (currentSize > maxSStableSizeInBytes)\n                sync();\n        }\n        catch (IOException e)\n        {\n            // addColumn does not throw IOException but we want to report this to the user,\n            // so wrap it in a temporary RuntimeException that we'll catch in rawAddRow above.\n            throw new SyncException(e);\n        }\n    }\n\n    private PartitionUpdate.Builder createPartitionUpdateBuilder(DecoratedKey key)\n    {\n        return new PartitionUpdate.Builder(metadata.get(), key, columns, 4)\n        {\n            @Override\n            public void add(Row row)\n            {\n                super.add(row);\n                countRow(row);\n                maybeSync();\n            }\n        };\n    }\n\n    @Override","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/io/sstable/SSTableSimpleUnsortedWriter.java#L112-L148","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Free disk space or provision more storage on the data directory filesystem","Check system logs (dmesg) for I/O errors and fix/replace failing disks or mounts","Retry the bulk load after resolving the storage issue; delete partial output sstables first","Wrap writer usage (add/close) in try-with-resources and handle SyncException by aborting and restarting the load cleanly"],"exampleFix":"// before\nwriter.addRow(key, values);\n// after\ntry {\n    writer.addRow(key, values);\n} catch (SyncException e) {\n    // disk flush/sync failed: check disk space/health, then restart the bulk load\n    throw new IllegalStateException(\"SSTable write sync failed: \" + e.getCause(), e);\n}","handlingStrategy":"try-catch","validationCode":"// check writable space before bulk loading\njava.io.File dataDir = new File(outputDir);\nif (dataDir.getUsableSpace() < requiredBytes) {\n    throw new IllegalStateException(\"insufficient disk space for sstable writer\");\n}\nif (!dataDir.canWrite()) throw new IllegalStateException(\"data dir not writable\");","typeGuard":null,"tryCatchPattern":"try (SSTableSimpleUnsortedWriter writer = createWriter(...)) {\n    writer.addRow(key, values);\n} catch (SyncException e) {\n    // flush/sync failed: log cause (IOException), check disk, restart load\n    throw new IllegalStateException(\"SSTable sync failed: \" + e.getCause(), e);\n}","preventionTips":["Ensure ample free disk space before bulk loads (monitor usable space)","Check disk health and mount options (not read-only) before writing","Use try-with-resources so writers are closed and flushed predictably","Delete partial output sstables after a failed load before retrying","Alert on filesystem full / I/O errors during bulk load operations"],"tags":["disk","io","sstable","write","bulk-load"],"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"}