apache/cassandra · critical · FSWriteError

FSWriteError

Error message

FSWriteError

What it means

In HintsWriteExecutor.flushInternal, appending hints to the hints file raised IOException (disk full, I/O error, permissions). It is converted to FSWriteError(e, file) — Cassandra's standard fatal disk-write failure — because hints durability cannot be compromised; the flush aborts and the node typically fails/gossips the disk error.

Source

Thrown at src/java/org/apache/cassandra/hints/HintsWriteExecutor.java:255

    private boolean flushInternal(Iterator<ByteBuffer> iterator, HintsWriter writer)
    {
        long maxHintsFileSize = DatabaseDescriptor.getMaxHintsFileSize();

        try (HintsWriter.Session session = writer.newSession(writeBuffer))
        {
            while (iterator.hasNext())
            {
                session.append(iterator.next());

                if (session.position() >= maxHintsFileSize)
                    return false;
            }

            return true;
        }
        catch (IOException e)
        {
            throw new FSWriteError(e, writer.descriptor().fileName());
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Check disk space and health on the hints volume; clean space or move hints_directory
2. Inspect the wrapped IOException in the log to identify disk vs. descriptor issues
3. After fixing storage, restart the node (hint writers are re-opened and buffered hints may be lost — run repair to be safe)
4. Monitor hints directory usage and alert before it fills

Example fix

# check and free space on the hints volume
df -h /var/lib/cassandra/hints
clean up or expand volume, then restart node and run nodetool repair

long usable = new File(hintsDirectory).getUsableSpace();
if (usable < MIN_FREE_BYTES) { logger.warn("Hints volume low: {} bytes free", usable); }

try {
    executor.flushBuffer();
} catch (FSWriteError e) {
    logger.error("Hints flush failed for {}: {}", fileName, e.getCause());
    // pause dispatch and page ops; run repair afterwards
}

When it happens

Trigger: Flushing the hint buffer to disk fails: disk full, I/O error during write or fsync, file closed unexpectedly, or device errors on the hints volume.

Common situations: Hints volume filling up; failing disk; hints file descriptor invalidated by external deletion; storage latency/timeout causing fsync failure.

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
• FSReadError
• Failed importing SSTables
• Unable to resolve canonical path for
• Digest mismatch exception

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