What causes "mountFuse: ConstructNode() failed: %s" in ipfs/kubo?

Run `ipfs repo fsck` and check for a stale repo lock; kill any other daemon using the same IPFS_PATH

mountFuse: ConstructNode() failed: %s

Error message

mountFuse: ConstructNode() failed: %s

What it means

mountFuse calls cctx.ConstructNode() to build the full IPFS node before mounting FUSE filesystems. If node construction fails — bad repo layout, unsupported repo version, datastore errors, invalid config values — the error is wrapped as "mountFuse: ConstructNode() failed". Mounting requires a fully constructed node because the mounts serve live blockstore/MFS data.

Source

Thrown at cmd/ipfs/kubo/daemon.go:1268

	nsdir, found := req.Options[ipnsMountKwd].(string)
	if !found {
		nsdir = cfg.Mounts.IPNS
	}
	if err := checkFusePath("Mounts.IPNS", nsdir); err != nil {
		return err
	}

	mfsdir, found := req.Options[mfsMountKwd].(string)
	if !found {
		mfsdir = cfg.Mounts.MFS
	}
	if err := checkFusePath("Mounts.MFS", mfsdir); err != nil {
		return err
	}

	node, err := cctx.ConstructNode()
	if err != nil {
		return fmt.Errorf("mountFuse: ConstructNode() failed: %s", err)
	}

	err = nodeMount.Mount(node, fsdir, nsdir, mfsdir)
	if err != nil {
		return err
	}
	// Extra space after "MFS" so "mounted at:" lines up with IPFS and
	// IPNS in the column above. Matches MountCmd's output formatter.
	fmt.Printf("IPFS mounted at: %s\n", fsdir)
	fmt.Printf("IPNS mounted at: %s\n", nsdir)
	fmt.Printf("MFS  mounted at: %s\n", mfsdir)
	return nil
}

func checkFusePath(name, path string) error {
	if path == "" {
		return fmt.Errorf("%s path cannot be empty", name)
	}

View on GitHub (pinned to 329838acdf)

Solutions

Run `ipfs repo fsck` and check for a stale repo lock; kill any other daemon using the same IPFS_PATH
Run `ipfs repo migrate` (or download the matching kubo version) if the repo version is newer than the binary
Read the wrapped inner error (%s) — it names the actual construction failure and fix that specific issue
Verify the repo datastore is intact and the disk is writable

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check: repo lock and version
if _, err := os.Stat(filepath.Join(ipfsPath, "repo.lock")); err == nil {
	// another daemon may hold the lock; stop it first
}
ipfsRepoVersion, _ := exec.Command("ipfs", "repo", "version").Output()

Try / catch

if err := mountFuse(req, cctx); err != nil {
	if strings.Contains(err.Error(), "ConstructNode() failed") {
		log.Printf("node construction failed: %v", err) // inner error names the real cause
	}
	return err
}

Prevention

Stop existing daemons before starting one with --mount (single repo lock holder)
Keep the kubo binary version >= repo version; run `ipfs repo migrate` after upgrades
Run `ipfs repo fsck` if construction failures persist
Validate datastore config changes on a scratch repo before applying them

When it happens

Trigger: Running `ipfs daemon --mount` when node construction fails: repo needs migration (repo version newer than binary), datastore is locked by another daemon, corrupt datastore, or invalid config values that fail validation during core construction.

Common situations: Attaching a mount to a repo while another daemon already holds the repo lock; running an older kubo against a repo written by a newer version; disk or datastore corruption; invalid Datastore or Mounts config entries.

Related errors

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