{"record":{"id":"47bd91ebbc8cdcf7","repo":"ipfs/kubo","slug":"mounting-s-w","errorCode":null,"errorMessage":"mounting %s: %w","messagePattern":"mounting (.+?): %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"fuse/mount/fuse.go","lineNumber":39,"sourceCode":"\n\tactive     bool\n\tactiveLock *sync.RWMutex\n\n\tunmountOnce sync.Once\n}\n\n// NewMount mounts a FUSE filesystem at a given location, and returns a Mount instance.\nfunc NewMount(root fs.InodeEmbedder, mountpoint string, opts *fs.Options) (Mount, error) {\n\tPlatformMountOpts(&opts.MountOptions)\n\tif opts.RootStableAttr == nil {\n\t\topts.RootStableAttr = &fs.StableAttr{Ino: RootIno}\n\t}\n\tif opts.FirstAutomaticIno == 0 {\n\t\topts.FirstAutomaticIno = AutomaticIno\n\t}\n\tserver, err := fs.Mount(mountpoint, root, opts)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"mounting %s: %w\", mountpoint, err)\n\t}\n\n\tm := &mount{\n\t\tmpoint:     mountpoint,\n\t\tserver:     server,\n\t\tactive:     true,\n\t\tactiveLock: &sync.RWMutex{},\n\t}\n\n\t// Detect external unmount (e.g. fusermount -u) so IsActive\n\t// returns false and Unmount returns ErrNotMounted.\n\tgo func() {\n\t\tserver.Wait()\n\t\tm.setActive(false)\n\t}()\n\n\tlog.Infof(\"Mounted %s\", mountpoint)\n\treturn m, nil","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/fuse/mount/fuse.go#L21-L57","documentation":"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.","triggerScenarios":"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).","commonSituations":"Docker containers lacking FUSE devices, macOS without macFUSE installed, Windows without WinFsp, or a stale mountpoint left behind by a crashed daemon.","solutions":["Install/verify the FUSE stack: /dev/fuse exists and fusermount3 is in PATH (Linux), macFUSE (macOS), WinFsp (Windows)","Unmount any stale mount at the path: fusermount3 -u <path>, or choose a new mountpoint","Run the daemon in an environment permitting FUSE (container: add device + SYS_ADMIN cap)","If FUSE is unavailable, use the HTTP gateway or ipfs files API instead of mounting"],"exampleFix":"// before\nm, err := fuse.NewMount(ctx, node, path.Join(dir, \"mfs\"), nil)\nif err != nil { log.Fatal(err) }\n// after\nm, err := fuse.NewMount(ctx, node, path.Join(dir, \"mfs\"), nil)\nif err != nil {\n    log.Warnf(\"FUSE unavailable, skipping mount: %v\", err)\n    return nil // fall back to gateway/API usage\n}","handlingStrategy":"fallback","validationCode":"if _, err := os.Stat(\"/dev/fuse\"); err != nil {\n    return fmt.Errorf(\"FUSE unavailable on this host: %w\", err)\n}\nif _, err := exec.LookPath(\"fusermount3\"); err != nil {\n    if _, err := exec.LookPath(\"fusermount\"); err != nil { return err }\n}\nif _, err := os.Stat(mountpoint); err != nil { return err }","typeGuard":null,"tryCatchPattern":"m, err := fuse.NewMount(ctx, node, mp, nil)\nif err != nil {\n    log.Warnf(\"mount failed (%v); falling back to HTTP gateway\", err)\n    useGatewayInstead()\n    return nil\n}","preventionTips":["Verify /dev/fuse and fusermount3 exist before enabling mounts","In containers, expose /dev/fuse and grant the needed capabilities","Choose fresh mountpoint paths to avoid stale-mount conflicts","Install macFUSE (macOS) / WinFsp (Windows) where applicable"],"tags":["fuse","mount","filesystem"],"backgroundTag":"fuse-mount-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"}