{"record":{"id":"801af999b94def3a","repo":"clockworklabs/SpacetimeDB","slug":"failed-to-open-directory-for-fsync","errorCode":null,"errorMessage":"failed to open directory {} for fsync: {}","messagePattern":"failed to open directory (.+?) for fsync: (.+?)","errorType":"exception","errorClass":"io::Error","httpStatus":null,"severity":"error","filePath":"crates/snapshot/src/lib.rs","lineNumber":1581,"sourceCode":"    Dir(&'a Path),\n}\n\nimpl FileOrDirPath<'_> {\n    /// `fsync` the file or directory at path `self`.\n    ///\n    /// On *nix systems, both a file and its enclosing directory should be\n    /// `fsync`ed to make the file durable.\n    ///\n    /// On Windows, only the file needs to be synced, and it's even an error to\n    /// sync a directory. Passing in [Self::Dir] is thus a no-op on Windows.\n    fn sync_all(&self) -> io::Result<()> {\n        match self {\n            #[cfg(target_os = \"windows\")]\n            Self::Dir(path) => Ok(()),\n            #[cfg(not(target_os = \"windows\"))]\n            Self::Dir(path) => File::open(path)\n                .map_err(|e| {\n                    io::Error::new(\n                        e.kind(),\n                        format!(\"failed to open directory {} for fsync: {}\", path.display(), e),\n                    )\n                })?\n                .sync_all()\n                .map_err(|e| io::Error::new(e.kind(), format!(\"failed to fsync directory {}: {}\", path.display(), e))),\n            Self::File(path) => {\n                File::options()\n                    .read(true)\n                    // Windows needs the file to be writable for `sync_all` to work.\n                    // Set all the open options explicitly, just for visibility.\n                    .write(true)\n                    .truncate(false)\n                    .create(false)\n                    .append(false)\n                    .open(path)\n                    .map_err(|e| {\n                        io::Error::new(","sourceCodeStart":1563,"sourceCodeEnd":1599,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/snapshot/src/lib.rs#L1563-L1599","documentation":"Part of the snapshot crate's durability sync (SyncTarget::sync_all): on Unix, a newly written snapshot file's enclosing directory must also be fsynced so the directory entry itself survives a crash. This variant wraps the failure to File::open the directory path, preserving the original error kind - the directory could not be opened at all.","triggerScenarios":"Saving/syncing a snapshot when the snapshot directory was deleted or renamed concurrently (cleanup job racing the snapshot); the path exists but is not a directory (ENOTDIR); the process lacks permission on the directory.","commonSituations":"Concurrent snapshot GC deleting directories while a snapshot is being finalized; snapshot root misconfigured to a file path; permission changes on a shared volume.","solutions":["Stop concurrent deletion/cleanup jobs that race with snapshot creation.","Verify the configured snapshot directory exists and is writable before starting.","Fix permissions on the snapshot root.","Retry the snapshot once the environment is stable."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"use std::fs;\n\nfn snapshot_dir_ready(dir: &str) -> std::io::Result<()> {\n    let md = fs::metadata(dir)?;\n    if !md.is_dir() {\n        return Err(std::io::Error::new(std::io::ErrorKind::NotADirectory, dir));\n    }\n    Ok(())\n}","typeGuard":null,"tryCatchPattern":"match sync_result {\n    Err(e) if e.to_string().contains(\"failed to open directory\") => {\n        // Directory vanished or is not a directory: stop racing cleanup jobs,\n        // recreate the directory, then retry the snapshot.\n    }\n    r => r,\n}","preventionTips":["Do not run snapshot cleanup/GC concurrently with snapshot creation on the same root.","Verify the snapshot root exists, is a directory, and is writable at startup.","Alert on permission changes to snapshot volumes."],"tags":["snapshot","fsync","filesystem","rust"],"backgroundTag":"fsync-failure","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}