ipfs/kubo · error

failed to initialize MFS root from %s stored at %s: %w. If c

Error message

failed to initialize MFS root from %s stored at %s: %w. If corrupted, use 'ipfs files chroot' to reset (see --help)

What it means

This error occurs at daemon startup when Kubo cannot construct the MFS (Mutable File System) root DAG from the CID stored in the datastore under the files root key. It wraps the underlying error (e.g. a missing or corrupt block) and points to the documented recovery: 'ipfs files chroot' resets the MFS root. It is thrown because MFS state persisted in the repo datastore must be consistent for the daemon to start with a working files API.

Source

Thrown at core/node/core.go:289

		}
		mfsOpts, err := cfg.Import.MFSRootOptions()
		if err != nil {
			return nil, fmt.Errorf("failed to build MFS options from Import config: %w", err)
		}

		// Keep dag here an online (network-backed) DAGService. "ipfs files cp
		// /ipfs/<cid> /path" stores a lazy pointer: only the referenced root is
		// fetched, and its children are pulled from the network on demand when
		// the tree is later traversed ("files ls -l", or "stat"/"read" of a
		// subpath). Do NOT swap in an offline/local-only DAGService to avoid an
		// under-lock bitswap hang, that turns those lazy lookups into "block not
		// found locally" errors. The GC-vs-MFS wedge that tempts that change
		// (ipfs/kubo#10842) is fixed on the GC side instead: MFS mutations hold
		// the pin lock and GC snapshots the MFS root under the GC lock, so live
		// MFS blocks are never collected out from under an in-flight write.
		root, err := mfs.NewRoot(ctx, dag, nd, pf, prov, mfsOpts...)
		if err != nil {
			return nil, fmt.Errorf("failed to initialize MFS root from %s stored at %s: %w. "+
				"If corrupted, use 'ipfs files chroot' to reset (see --help)", nd.Cid(), FilesRootDatastoreKey, err)
		}

		lc.Append(fx.Hook{
			OnStop: func(ctx context.Context) error {
				return shutdown.CloseWithCtx(ctx, "mfs-root", root.Close)
			},
		})

		return root, err
	}
}

View on GitHub (pinned to 329838acdf)

Solutions

1. Run `ipfs files chroot /` (see `ipfs files chroot --help`) to reset the MFS root to a new empty directory
2. Run `ipfs repo fsck`/`ipfs datastore verify` style diagnostics to assess datastore damage and restore from backup if needed
3. If blocks are missing but recoverable, re-add or re-fetch the content, then retry daemon start

Example fix

// before
ipfs daemon
// Error: failed to initialize MFS root from <cid> stored at /local/filesroot: ...
// after
ipfs files chroot /
ipfs daemon

// Before starting the daemon, verify the MFS root resolves
rootCID, err := node.Repo.Datastore().Get(ctx, ds.NewKey("/local/filesroot"))
if err != nil {
	// no MFS root yet; `ipfs files chroot /` will create one
	_ = err
}
_ = rootCID

if _, err := mfs.NewRoot(ctx, dag, nd, pf, prov, opts...); err != nil {
	var bstoreErr *blockstore.ErrNotFound
	if errors.As(err, &bstoreErr) {
		// corrupted/missing root: reset MFS root
		// ipfs files chroot /
	}
	return fmt.Errorf("failed to initialize MFS root: %w", err)
}

When it happens

Trigger: Daemon start (core/node construction) calls mfs.NewRoot with the node CID read from the datastore at FilesRootDatastoreKey; construction fails when the root CID cannot be resolved, e.g. the root block or child blocks were lost or corrupted in the datastore.

Common situations: Datastore corruption after disk failure or unclean shutdown; blocks removed by manual datastore surgery; restoring a repo partially; a GC bug or manual `ipfs repo gc` variants removing live blocks.

Related errors

• failure writing filesroot to dagstore: %s
• error loading filesroot from dagservice: %s
• failed to get config: %w
• failed to build MFS options from Import config: %w
• provider: error flushing MFS: %w

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