clockworklabs/SpacetimeDB · error · io::Error

failed to fsync directory {}: {}

Error message

failed to fsync directory {}: {}

What it means

Same durability sync: the snapshot directory opened successfully, but the sync_all syscall on it failed. This is a low-level I/O error from the filesystem or device while flushing directory metadata; the snapshot's directory entries are not guaranteed crash-durable.

Source

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

    /// On *nix systems, both a file and its enclosing directory should be
    /// `fsync`ed to make the file durable.
    ///
    /// On Windows, only the file needs to be synced, and it's even an error to
    /// sync a directory. Passing in [Self::Dir] is thus a no-op on Windows.
    fn sync_all(&self) -> io::Result<()> {
        match self {
            #[cfg(target_os = "windows")]
            Self::Dir(path) => Ok(()),
            #[cfg(not(target_os = "windows"))]
            Self::Dir(path) => File::open(path)
                .map_err(|e| {
                    io::Error::new(
                        e.kind(),
                        format!("failed to open directory {} for fsync: {}", path.display(), e),
                    )
                })?
                .sync_all()
                .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)))

View on GitHub (pinned to 524b4487d9)

Solutions

1. Move snapshot storage to a local POSIX filesystem.
2. Check disk health and free space.
3. Re-run the snapshot; treat the previous attempt as not durable.

match sync_result {
    Err(e) if e.to_string().contains("failed to fsync directory") => {
        // Low-level durability failure: check disk/filesystem, then re-run the
        // snapshot from scratch; the previous attempt is not durable.
    }
    r => r,
}

When it happens

Trigger: Dir(path).sync_all() returning an error: device or filesystem failure, network filesystems that do not support directory fsync, or ENOSPC-like conditions at flush time.

Common situations: Snapshot storage placed on NFS/SMB or exotic filesystems; failing disks; volumes that run full under heavy write load.

Related errors

• failed to open directory {} for fsync: {}
• failed to open file {} for fsync: {}
• failed to fsync file {}: {}
• AlreadyExists
• repo {}: error getting file metadata for segment {}: {}

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