What causes "Error flushing page {pageIndex} to device" in microsoft/FASTER?

Check free disk space and the underlying device error; free space or remount storage and retry the checkpoint.

microsoft/FASTER · error · FasterException

Error flushing page to device

Error message

Error flushing page {pageIndex} to device

What it means

Recovery.WaitFlush blocks until the flush of pageIndex completes (flushStatus leaves Pending), then throws FasterException if the flush ended in FlushStatus.Error. It propagates a device write failure encountered while flushing log pages during checkpointing/commit. Called from WaitUntilAllPagesHaveBeenFlushed, so it aborts the checkpoint.

Solutions

Check free disk space and the underlying device error; free space or remount storage and retry the checkpoint.
Ensure the log/checkpoint devices are healthy and not disposed before flush completes.
Add retry logic around checkpointing, and configure an earlier checkpoint to roll back to if this one fails.

Example fix

// before
store.TakeFullCheckpoint(Guid.NewGuid()); // disk full
// after
EnsureDiskSpace(ckptDrive, requiredBytes: EstimateCheckpointSize(store));
store.TakeFullCheckpoint(Guid.NewGuid());

Defensive patterns

Strategy: try-catch

Validate before calling

var drive = new DriveInfo(Path.GetPathRoot(ckptDir));
if (drive.AvailableFreeSpace < estimatedCheckpointBytes)
    throw new IOException($"Insufficient space for checkpoint: need {estimatedCheckpointBytes}, have {drive.AvailableFreeSpace}");

Try / catch

try { store.TakeFullCheckpoint(guid); store.CompleteCheckpoint(); }
catch (FasterException ex) when (ex.Message.Contains("Error flushing page"))
{ logger.LogCritical(ex, "Checkpoint flush failed"); RollBackToLastGoodCheckpoint(); }

Prevention

Alert on free-disk-space thresholds well before checkpoints run.
Never dispose devices while checkpoints or commits are in flight.
Retain a known-good checkpoint to roll back to when a flush fails.

When it happens

Trigger: Taking a checkpoint or committing and waiting for all pages to flush when the device write of pageIndex fails — disk full, device handle closed, storage error, or unsupported device configuration.

Common situations: Disk-full during checkpoint, network storage blips with remote devices, or writing to a removable drive that was disconnected.

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 microsoft/FASTER@321d872eab (2026-09-15). Data as JSON: /api/errors/b0323ff32127fba3. Report an issue: GitHub.

Appendix: source

Thrown at cs/src/core/Index/Recovery/Recovery.cs:103

        internal void SignalFlushed(int pageIndex)
        {
            this.flushStatus[pageIndex] = FlushStatus.Done;
            this.flushSemaphore.Release();
        }

        internal void SignalFlushedError(int pageIndex)
        {
            this.flushStatus[pageIndex] = FlushStatus.Error;
            this.flushSemaphore.Release();
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        internal void WaitFlush(int pageIndex)
        {
            while (this.flushStatus[pageIndex] == FlushStatus.Pending)
                this.flushSemaphore.Wait();
            if (this.flushStatus[pageIndex] == FlushStatus.Error)
                throw new FasterException($"Error flushing page {pageIndex} to device");
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        internal async ValueTask WaitFlushAsync(int pageIndex, CancellationToken cancellationToken)
        {
            while (this.flushStatus[pageIndex] == FlushStatus.Pending)
                await this.flushSemaphore.WaitAsync(cancellationToken).ConfigureAwait(false);
            if (this.flushStatus[pageIndex] == FlushStatus.Error)
                throw new FasterException($"Error flushing page {pageIndex} to device");
        }

        internal void Dispose()
        {
            recoveryDevice.Dispose();
            objectLogRecoveryDevice.Dispose();
        }
    }

View on GitHub (pinned to 321d872eab)