ipfs/kubo · error

copying binary to stash: %w

Error message

copying binary to stash: %w

What it means

`stashBinary` backs up the currently installed kubo binary into `<IPFS_PATH>/stash/` before an update. This error wraps any failure of `io.Copy(dst, src)` while copying the binary bytes into the stash file, so the backup is incomplete and the update aborts rather than leaving the operator without a rollback binary.

Source

Thrown at core/commands/update.go:620

	src, err := os.Open(binPath)
	if err != nil {
		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

View on GitHub (pinned to 329838acdf)

Solutions

1. Check free space on the filesystem holding IPFS_PATH: `df -h "$IPFS_PATH"` and free space if full.
2. Confirm the current binary is readable: `cat "$(which ipfs)" > /dev/null` to surface read errors.
3. Delete the partial stash file (e.g. `$IPFS_PATH/stash/ipfs-<ver>`) and retry `ipfs update`.
4. If $IPFS_PATH is on flaky storage, move it to a reliable local disk or set IPFS_PATH to a healthy path for the update.

Example fix

// diagnosis
ls -lh "$IPFS_PATH/stash/"   # partial/zero-length stash file
df -h "$IPFS_PATH"           # 100% used
# after freeing space, remove the bad stash entry and retry
rm "$IPFS_PATH/stash/ipfs-0.30.0"
ipfs update

// before update: ensure the source binary is readable and space exists
stat, err := os.Stat(binPath)
if err != nil { /* cannot read current binary */ }
usage, _ := diskUsage(filepath.Dir(stashPath))
if usage.Free < stat.Size()+overhead { /* abort early: not enough space to stash */ }

stashPath, err := stashBinary(binPath, ver)
if err != nil {
	var perr *os.PathError
	if errors.As(err, &perr) {
		log.Printf("stash copy failed on %s: %v (check disk space/permissions)", perr.Path, perr.Err)
	}
	return fmt.Errorf("backup aborted, current binary untouched: %w", err)
}

When it happens

Trigger: An I/O error while streaming the current binary into the stash file: disk full during the copy, source file read error (permissions, device error), or an interrupted write to the destination file.

Common situations: Running `ipfs update` when the disk containing $IPFS_PATH is full; $IPFS_PATH on a network/USB mount that drops mid-copy; the ipfs binary on a read-only or removable medium whose read fails partway.

Related errors

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

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