ipfs/kubo · error

umount timeout

Error message

umount timeout

What it means

ForceUnmount runs a GOOS-specific unmount command (fusermount/fusermount3/diskutil) asynchronously and gives up after 7 seconds with the literal error 'umount timeout'. The unmount command hung, usually because processes still hold files open on the mount.

Source

Thrown at fuse/mount/mount.go:56

		return err
	}

	errc := make(chan error, 1)
	go func() {
		defer close(errc)

		// try vanilla unmount first.
		if err := exec.Command("umount", point).Run(); err == nil {
			return
		}

		// retry to unmount with the fallback cmd
		errc <- cmd.Run()
	}()

	select {
	case <-time.After(7 * time.Second):
		return fmt.Errorf("umount timeout")
	case err := <-errc:
		return err
	}
}

// UnmountCmd creates an exec.Cmd that is GOOS-specific
// for unmount a FUSE mount.
func UnmountCmd(point string) (*exec.Cmd, error) {
	switch runtime.GOOS {
	case "darwin":
		return exec.Command("diskutil", "umount", "force", point), nil
	case "linux":
		if _, err := exec.LookPath("fusermount3"); err == nil {
			return exec.Command("fusermount3", "-u", point), nil
		}
		return exec.Command("fusermount", "-u", point), nil
	default:
		return nil, fmt.Errorf("unmount: unimplemented")

View on GitHub (pinned to 329838acdf)

Solutions

1. Abort the FUSE connection first: echo 1 > /sys/fs/fuse/connections/<id>/abort, then fusermount3 -u -z <path>
2. Find and kill processes using the mount (fuser -vm <path>, lsof +f -- <path>) then retry
3. Clean up stale mounts under /tmp after crashed tests before re-running
4. Increase patience or run unmount lazily (-z) if busy unmounts are expected

Example fix

// manual recovery
connId=$(awk '$0 ~ /\/tmp\/TestMount/ {split($3,a,":"); print a[3]}' /proc/self/mountinfo)
echo 1 > /sys/fs/fuse/connections/$connId/abort
fusermount3 -u -z /tmp/TestMount123/001

// pre-check: no processes should hold the mount
exec.Command("fuser", "-vm", mountpoint).Run() // non-zero exit means free

if err := mount.ForceUnmount(m); err != nil && err.Error() == "umount timeout" {
    // abort the dead FUSE connection, then retry
    abortFuseConnection(mountpoint)
    time.Sleep(time.Second)
    err = mount.ForceUnmount(m)
}

When it happens

Trigger: ForceUnmount called while processes have open FDs or CWDs inside the mount and neither fusermount nor the fallback command completes within 7 seconds; dead FUSE connection blocking the unmount syscall.

Common situations: A crashed test left processes stuck in D state on a dead FUSE mount; NFS-like stalls; fusermount3 missing so fallback retries slowly.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• unmount %s failed after 10 seconds of trying
• not mounted
• unmount: unimplemented
• mountFuse: GetConfig() failed: %s
• mountFuse: ConstructNode() failed: %s

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