{"record":{"id":"230fc238634a64eb","repo":"ipfs/kubo","slug":"syncing-stash-file-w","errorCode":null,"errorMessage":"syncing stash file: %w","messagePattern":"syncing stash file: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/update.go","lineNumber":623,"sourceCode":"\t\treturn \"\", fmt.Errorf(\"opening current binary: %w\", err)\n\t}\n\tdefer src.Close()\n\n\tdst, err := os.OpenFile(stashPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o755)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"creating stash file: %w\", err)\n\t}\n\tdefer func() {\n\t\tif cerr := dst.Close(); cerr != nil && err == nil {\n\t\t\terr = fmt.Errorf(\"writing stash file: %w\", cerr)\n\t\t}\n\t}()\n\n\tif _, err = io.Copy(dst, src); err != nil {\n\t\treturn \"\", fmt.Errorf(\"copying binary to stash: %w\", err)\n\t}\n\tif err = dst.Sync(); err != nil {\n\t\treturn \"\", fmt.Errorf(\"syncing stash file: %w\", err)\n\t}\n\n\treturn stashPath, nil\n}\n\n// stashEntry describes a single backed-up Kubo binary in the stash directory.\ntype stashEntry struct {\n\tpath   string\n\tname   string\n\tver    string\n\tparsed *goversion.Version\n\tsize   int64\n}\n\n// listStashes returns every stashed binary in dir, newest first. Files that\n// do not match the \"ipfs-<semver>\" naming convention are skipped so the\n// directory can hold unrelated user files without breaking revert/clean.\nfunc listStashes(dir string) ([]stashEntry, error) {","sourceCodeStart":605,"sourceCodeEnd":641,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/update.go#L605-L641","documentation":"`stashBinary` calls `dst.Sync()` to flush the backed-up binary to stable storage before declaring the stash valid. This error wraps a Sync failure, meaning the OS could not persist the stash file's data; the update aborts so the operator is never left trusting a possibly-unflushed rollback binary.","triggerScenarios":"`fsync` on the open stash file fails: underlying device errors, file on a filesystem that does not support fsync, or an I/O error already pending on the file descriptor (e.g. from a failed write).","commonSituations":"$IPFS_PATH on NFS/SMB/CIFS mounts where fsync is unsupported or flaky; failing disk sectors; running in a container whose writable layer cannot fsync; USB storage disconnecting mid-update.","solutions":["Check `dmesg`/journal for underlying device I/O errors and run a filesystem check (fsck) if errors are reported.","If IPFS_PATH is on a network mount (NFS/SMB), run the update from a local-disk IPFS_PATH.","Remove the partial stash file and retry `ipfs update` once the storage issue is resolved.","If fsync is consistently unsupported (some FUSE/network mounts), the practical fix is a local filesystem; report persistent cases upstream."],"exampleFix":"// before (fails)\nIPFS_PATH=/mnt/nfs/home/.ipfs ipfs update\n\n// after (use local disk for the update)\nexport IPFS_PATH=/var/lib/ipfs\nipfs update","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := dst.Sync(); err != nil {\n\t// treat as fatal: the backup cannot be trusted\n\treturn fmt.Errorf(\"backup aborted, current binary untouched: %w\", err)\n}","preventionTips":["Keep IPFS_PATH on a local POSIX filesystem (ext4/xfs/btrfs), not NFS/SMB/FUSE.","Monitor SMART/device health; run fsck after any reported I/O error.","Retry the update after transient storage failures — Sync errors are rarely persistent on healthy disks.","Test fsync support on exotic mounts before hosting IPFS_PATH there: write+fsync a probe file."],"tags":["io","filesystem","fsync","update"],"backgroundTag":"fsync-failed","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}