ipfs/kubo · error

syncing stash file: %w

Error message

syncing stash file: %w

What it means

`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.

Source

Thrown at core/commands/update.go:623

		return "", fmt.Errorf("opening current binary: %w", err)
	}
	defer src.Close()

	dst, err := os.OpenFile(stashPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o755)
	if err != nil {
		return "", fmt.Errorf("creating stash file: %w", err)
	}
	defer func() {
		if cerr := dst.Close(); cerr != nil && err == nil {
			err = fmt.Errorf("writing stash file: %w", cerr)
		}
	}()

	if _, err = io.Copy(dst, src); err != nil {
		return "", fmt.Errorf("copying binary to stash: %w", err)
	}
	if err = dst.Sync(); err != nil {
		return "", fmt.Errorf("syncing stash file: %w", err)
	}

	return stashPath, nil
}

// stashEntry describes a single backed-up Kubo binary in the stash directory.
type stashEntry struct {
	path   string
	name   string
	ver    string
	parsed *goversion.Version
	size   int64
}

// listStashes returns every stashed binary in dir, newest first. Files that
// do not match the "ipfs-<semver>" naming convention are skipped so the
// directory can hold unrelated user files without breaking revert/clean.
func listStashes(dir string) ([]stashEntry, error) {

View on GitHub (pinned to 329838acdf)

Solutions

1. Check `dmesg`/journal for underlying device I/O errors and run a filesystem check (fsck) if errors are reported.
2. If IPFS_PATH is on a network mount (NFS/SMB), run the update from a local-disk IPFS_PATH.
3. Remove the partial stash file and retry `ipfs update` once the storage issue is resolved.
4. If fsync is consistently unsupported (some FUSE/network mounts), the practical fix is a local filesystem; report persistent cases upstream.

Example fix

// before (fails)
IPFS_PATH=/mnt/nfs/home/.ipfs ipfs update

// after (use local disk for the update)
export IPFS_PATH=/var/lib/ipfs
ipfs update

if err := dst.Sync(); err != nil {
	// treat as fatal: the backup cannot be trusted
	return fmt.Errorf("backup aborted, current binary untouched: %w", err)
}

When it happens

Trigger: `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).

Common situations: $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.

Related errors

• flushing %s: %w
• copying binary to stash: %w
• syncing temp file: %w
• unexpected error while checking writeablility of repo root:
• reading stash directory: %w

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/230fc238634a64eb. Report an issue: GitHub.