clockworklabs/SpacetimeDB · error · io::Error

failed to fsync file {}: {}

Error message

failed to fsync file {}: {}

What it means

The final durability step for a snapshot file: the file opened fine, but sync_all() on it returned an error. The file's data was not flushed to stable storage, so the snapshot must be treated as potentially incomplete after a crash.

Source

Thrown at crates/snapshot/src/lib.rs:1605

                .map_err(|e| io::Error::new(e.kind(), format!("failed to fsync directory {}: {}", path.display(), e))),
            Self::File(path) => {
                File::options()
                    .read(true)
                    // Windows needs the file to be writable for `sync_all` to work.
                    // Set all the open options explicitly, just for visibility.
                    .write(true)
                    .truncate(false)
                    .create(false)
                    .append(false)
                    .open(path)
                    .map_err(|e| {
                        io::Error::new(
                            e.kind(),
                            format!("failed to open file {} for fsync: {}", path.display(), e),
                        )
                    })?
                    .sync_all()
                    .map_err(|e| io::Error::new(e.kind(), format!("failed to fsync file {}: {}", path.display(), e)))
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use std::fs::OpenOptions;

    use tempfile::tempdir;

    use super::*;

    #[test]
    fn listing_ignores_if_snapshot_file_is_missing() -> anyhow::Result<()> {
        let tmp = tempdir()?;

        let root = SnapshotsPath::from_path_unchecked(tmp.path());

View on GitHub (pinned to 524b4487d9)

Solutions

1. Check disk health and free space immediately.
2. Re-run the snapshot and do not trust the un-synced file.
3. Use storage with reliable flush semantics (local SSD rather than thin-provisioned network volumes).

match sync_result {
    Err(e) if e.to_string().contains("failed to fsync file") => {
        // Device-level flush failure: check disk health/space, discard the snapshot,
        // and retry once storage is stable.
    }
    r => r,
}

When it happens

Trigger: Device-level I/O errors during fsync; ENOSPC surfacing at flush time on write-back filesystems (ext4 delayed allocation); virtualized storage with unreliable flush semantics.

Common situations: Disks failing under fsync load; disk full at flush time; thin-provisioned network volumes that acknowledge writes before they are durable.

Related errors

• failed to open directory {} for fsync: {}
• failed to fsync directory {}: {}
• failed to open file {} for fsync: {}
• failed to flush segment upon rotation
• fsync failed

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/89aad2c97b0c2d86. Report an issue: GitHub.