{"record":{"id":"e479e4cec46b723d","repo":"ipfs/kubo","slug":"syncing-temp-file-w","errorCode":null,"errorMessage":"syncing temp file: %w","messagePattern":"syncing temp file: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/update.go","lineNumber":738,"sourceCode":"\tpattern := migrations.ExeName(fmt.Sprintf(\"ipfs-%s-*\", ver))\n\tf, err := os.CreateTemp(\"\", pattern)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"creating temp file: %w\", err)\n\t}\n\tdefer func() {\n\t\tif cerr := f.Close(); cerr != nil && err == nil {\n\t\t\terr = fmt.Errorf(\"closing temp file: %w\", cerr)\n\t\t}\n\t\tif err != nil {\n\t\t\tos.Remove(f.Name())\n\t\t}\n\t}()\n\n\tif _, err = f.Write(data); err != nil {\n\t\treturn \"\", fmt.Errorf(\"writing temp file: %w\", err)\n\t}\n\tif err = f.Sync(); err != nil {\n\t\treturn \"\", fmt.Errorf(\"syncing temp file: %w\", err)\n\t}\n\tif err = f.Chmod(0o755); err != nil {\n\t\treturn \"\", fmt.Errorf(\"chmod temp file: %w\", err)\n\t}\n\treturn f.Name(), nil\n}\n\n// extractBinaryFromArchive extracts the kubo/ipfs binary from a tar.gz or zip archive.\nfunc extractBinaryFromArchive(data []byte) ([]byte, error) {\n\tbinName := migrations.ExeName(\"ipfs\")\n\n\t// Try tar.gz first (Unix releases), then zip (Windows releases).\n\tresult, tarErr := extractFromTarGz(data, binName)\n\tif tarErr == nil {\n\t\treturn result, nil\n\t}\n\n\tresult, zipErr := extractFromZip(data, binName)","sourceCodeStart":720,"sourceCodeEnd":756,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/update.go#L720-L756","documentation":"`writeBinaryToTempFile` calls `f.Sync()` to guarantee the staged binary bytes reached stable storage before the file is used to replace the live binary. This error wraps a failing fsync; kubo aborts rather than atomically swapping in a binary whose durability is unverified.","triggerScenarios":"`ipfs update install` when fsync on the temp executable fails: unsupported filesystem (some FUSE/NFS mounts), pending I/O error on the descriptor, or device-level failure.","commonSituations":"TMPDIR on NFS/SMB or a FUSE mount that rejects fsync; flaky external drive as TMPDIR; overlayfs quirks in restricted containers; storage hardware failures.","solutions":["Point TMPDIR at a standard local filesystem: `export TMPDIR=/var/tmp` (ext4/xfs/btrfs) and rerun the update.","Check `dmesg` for device I/O errors and run fsck if indicated.","If on a network/FUSE mount by necessity, stage via a local dir first — the update flow always uses the OS temp dir, so TMPDIR is the lever.","Retry once after a transient failure; the partial file is cleaned up automatically."],"exampleFix":"# before\nexport TMPDIR=/mnt/nfs/tmp\nipfs update install v0.30.0   # syncing temp file: ... invalid argument\n\n# after\nexport TMPDIR=/var/tmp\nipfs update install v0.30.0","handlingStrategy":"fallback","validationCode":"// verify fsync works on the temp dir before updating\ndir := os.TempDir()\nprobe, _ := os.CreateTemp(dir, \".fsync-probe-*\")\nif err := probe.Sync(); err != nil {\n\t// fsync unsupported here: switch TMPDIR to a local FS first\n}\nprobe.Close()\nos.Remove(probe.Name())","typeGuard":"func supportsFsync(dir string) bool {\n\tf, err := os.CreateTemp(dir, \".probe-*\")\n\tif err != nil {\n\t\treturn false\n\t}\n\tdefer f.Close()\n\tdefer os.Remove(f.Name())\n\treturn f.Sync() == nil\n}","tryCatchPattern":"path, err := writeBinaryToTempFile(data, ver)\nif err != nil {\n\tif strings.Contains(err.Error(), \"syncing temp file\") {\n\t\t// fallback: repoint TMPDIR to a local POSIX filesystem and retry\n\t\tos.Setenv(\"TMPDIR\", \"/var/tmp\")\n\t\treturn retryUpdate()\n\t}\n\treturn err\n}","preventionTips":["Host TMPDIR on ext4/xfs/btrfs, never NFS/SMB/FUSE mounts.","Test fsync support on any unusual mount before using it for temp files.","Treat fsync errors as storage-health signals; check dmesg and fsck when they recur.","Standardize TMPDIR in deployment scripts rather than inheriting the ambient value."],"tags":["io","fsync","temp-file","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"}