ipfs/kubo · error

mounting %s: %w

Error message

mounting %s: %w

What it means

NewMount wraps a failure from go-fuse's fs.Mount with 'mounting <path>: <reason>'. The FUSE filesystem could not be mounted at the given mountpoint, e.g. missing /dev/fuse, missing fusermount binary, busy path, or no permissions.

Source

Thrown at fuse/mount/fuse.go:39

	active     bool
	activeLock *sync.RWMutex

	unmountOnce sync.Once
}

// NewMount mounts a FUSE filesystem at a given location, and returns a Mount instance.
func NewMount(root fs.InodeEmbedder, mountpoint string, opts *fs.Options) (Mount, error) {
	PlatformMountOpts(&opts.MountOptions)
	if opts.RootStableAttr == nil {
		opts.RootStableAttr = &fs.StableAttr{Ino: RootIno}
	}
	if opts.FirstAutomaticIno == 0 {
		opts.FirstAutomaticIno = AutomaticIno
	}
	server, err := fs.Mount(mountpoint, root, opts)
	if err != nil {
		return nil, fmt.Errorf("mounting %s: %w", mountpoint, err)
	}

	m := &mount{
		mpoint:     mountpoint,
		server:     server,
		active:     true,
		activeLock: &sync.RWMutex{},
	}

	// Detect external unmount (e.g. fusermount -u) so IsActive
	// returns false and Unmount returns ErrNotMounted.
	go func() {
		server.Wait()
		m.setActive(false)
	}()

	log.Infof("Mounted %s", mountpoint)
	return m, nil

View on GitHub (pinned to 329838acdf)

Solutions

1. Install/verify the FUSE stack: /dev/fuse exists and fusermount3 is in PATH (Linux), macFUSE (macOS), WinFsp (Windows)
2. Unmount any stale mount at the path: fusermount3 -u <path>, or choose a new mountpoint
3. Run the daemon in an environment permitting FUSE (container: add device + SYS_ADMIN cap)
4. If FUSE is unavailable, use the HTTP gateway or ipfs files API instead of mounting

Example fix

// before
m, err := fuse.NewMount(ctx, node, path.Join(dir, "mfs"), nil)
if err != nil { log.Fatal(err) }
// after
m, err := fuse.NewMount(ctx, node, path.Join(dir, "mfs"), nil)
if err != nil {
    log.Warnf("FUSE unavailable, skipping mount: %v", err)
    return nil // fall back to gateway/API usage
}

if _, err := os.Stat("/dev/fuse"); err != nil {
    return fmt.Errorf("FUSE unavailable on this host: %w", err)
}
if _, err := exec.LookPath("fusermount3"); err != nil {
    if _, err := exec.LookPath("fusermount"); err != nil { return err }
}
if _, err := os.Stat(mountpoint); err != nil { return err }

m, err := fuse.NewMount(ctx, node, mp, nil)
if err != nil {
    log.Warnf("mount failed (%v); falling back to HTTP gateway", err)
    useGatewayInstead()
    return nil
}

When it happens

Trigger: Calling NewMount for a mountpoint that does not exist, is already in use, or in an environment without FUSE support (no /dev/fuse, unprivileged user without fusermount3, container without --device /dev/fuse --cap-add SYS_ADMIN).

Common situations: Docker containers lacking FUSE devices, macOS without macFUSE installed, Windows without WinFsp, or a stale mountpoint left behind by a crashed daemon.

Related errors

• %s path (%q) does not exist: %w
• mountFuse: GetConfig() failed: %s
• mountFuse: ConstructNode() failed: %s
• %s path cannot be empty
• cannot manually publish while IPNS is mounted

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