apache/cassandra · critical · FSWriteError

FSWriteError

Error message

FSWriteError

What it means

FSWriteError thrown by HintsStore.openWriter when HintsWriter.create fails with an IOException while opening/creating a hints file for a new descriptor. Wrapped by getOrOpenWriter whenever a hints writer is needed.

Source

Thrown at src/java/org/apache/cassandra/hints/HintsStore.java:366

    }

    HintsWriter getWriter()
    {
        return hintsWriter;
    }

    private HintsWriter openWriter()
    {
        lastUsedTimestamp = Math.max(currentTimeMillis(), lastUsedTimestamp + 1);
        HintsDescriptor descriptor = new HintsDescriptor(hostId, lastUsedTimestamp, writerParams);

        try
        {
            return HintsWriter.create(hintsDirectory, descriptor);
        }
        catch (IOException e)
        {
            throw new FSWriteError(e, descriptor.fileName());
        }
    }

    void closeWriter()
    {
        if (hintsWriter != null)
        {
            hintsWriter.close();
            offerLast(hintsWriter.descriptor());
            hintsWriter = null;
            SyncUtil.trySyncDir(hintsDirectory);
        }
    }

    void fsyncWriter()
    {
        if (hintsWriter != null)
            hintsWriter.fsync();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Check disk space on the hints volume (df -h) and free space or relocate hints_directory
  2. Verify the hints directory exists and cassandra can write to it (ls -ld, chown)
  3. Raise the open-file ulimit if the log shows 'Too many open files'
  4. Fix underlying disk I/O errors indicated by the wrapped IOException cause, then restart hint dispatch

Example fix

# before: openWriter fails
mkdir -p /var/lib/cassandra/hints
chown cassandra:cassandra /var/lib/cassandra/hints
chmod 750 /var/lib/cassandra/hints
Defensive patterns

Strategy: try-catch

Validate before calling

// precondition check before triggering hint writes
File dir = new File(hintsDirectory);
if (!dir.isDirectory() || !dir.canWrite()) throw new IllegalStateException("Hints dir not writable: " + hintsDirectory);

Try / catch

try {
    store.getOrOpenWriter();
} catch (FSWriteError e) {
    logger.error("Cannot open hints writer for {} : {}", file, e.getCause());
    // alert/pause dispatch until storage issue is resolved
}

Prevention

When it happens

Trigger: Creating a new hints file in the hints directory fails: directory missing, no write permission, disk full, too many open files, or I/O error on file creation.

Common situations: Disk full on the hints volume; hints directory permissions broken after restore/migration; ulimit -n too low (EMFILE); hints directory deleted while node runs.

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

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