ipfs/kubo · error

provider: error loading MFS root: %w

Error message

provider: error loading MFS root: %w

What it means

Returned by mfsWalkProvider after a successful FlushMemFree, when mfsRoot.GetDirectory().GetNode() fails to load the root directory's IPLD node from the blockstore. This aborts the +unique/+entities MFS reprovide walk. The wrapped error carries the blockstore/datastore-level cause.

Source

Thrown at core/node/provider.go:1289

// mfsEntityRootsProvider is the +entities counterpart. It walks with
// WalkEntityRoots, emitting only entity roots and skipping file chunks.
func mfsEntityRootsProvider(mfsRoot *mfs.Root, bs blockstore.Blockstore, tracker walker.VisitedTracker) provider.KeyChanFunc {
	walk := func(ctx context.Context, root cid.Cid, emit func(cid.Cid) bool, opts ...walker.Option) error {
		return walker.WalkEntityRoots(ctx, root, walker.NodeFetcherFromBlockstore(bs), emit, opts...)
	}
	return mfsWalkProvider(mfsRoot, bs, tracker, walk)
}

// mfsWalkProvider builds a KeyChanFunc that flushes MFS, then walks
// with the given walkFunc using a shared tracker and locality check.
func mfsWalkProvider(mfsRoot *mfs.Root, bs blockstore.Blockstore, tracker walker.VisitedTracker, walk walkFunc) provider.KeyChanFunc {
	return func(ctx context.Context) (<-chan cid.Cid, error) {
		if err := mfsRoot.FlushMemFree(ctx); err != nil {
			return nil, fmt.Errorf("provider: error flushing MFS: %w", err)
		}
		rootNode, err := mfsRoot.GetDirectory().GetNode()
		if err != nil {
			return nil, fmt.Errorf("provider: error loading MFS root: %w", err)
		}

		ch := make(chan cid.Cid)
		go func() {
			defer close(ch)
			locality := func(ctx context.Context, c cid.Cid) (bool, error) {
				return bs.Has(ctx, c)
			}
			_ = walk(ctx, rootNode.Cid(), func(c cid.Cid) bool {
				select {
				case ch <- c:
					return true
				case <-ctx.Done():
					return false
				}
			}, walker.WithVisitedTracker(tracker), walker.WithLocality(locality))
		}()
		return ch, nil

View on GitHub (pinned to 329838acdf)

Solutions

1. Read the wrapped error in the daemon log to find the underlying blockstore cause
2. Run repo integrity checks / 'ipfs repo fsck'; repair or restore the datastore
3. Restart the daemon and let the next reprovide cycle retry
4. If MFS root blocks are unrecoverable, recreate MFS ('ipfs files') and re-pin needed content

rootNode, err := mfsRoot.GetDirectory().GetNode()
if err != nil {
    return fmt.Errorf("MFS root unreadable, +unique/+entities MFS reprovide will fail: %w", err)
}

if rootNode == nil || !rootNode.Cid().Defined() {
    // invalid root node
}

_, err := keyChanFunc(ctx)
if err != nil && strings.Contains(err.Error(), "provider: error loading MFS root") {
    // trigger repo check/repair before retrying
}

When it happens

Trigger: Reprovide cycle using '+unique' or '+entities' with the 'mfs' base while the MFS root node read fails: missing/corrupt root block, blockstore I/O error, or datastore returning not-found for the MFS root CID.

Common situations: Corrupted blockstore after unclean shutdown, deleted blocks under a misconfigured GC, version-mismatched repo, or disk I/O failure.

Related errors

• provider: error loading MFS root, cannot provide MFS: %w
• provider: error flushing MFS: %w
• bloom tracker: %w
• provider: +unique requires pinned and/or mfs
• block %s not found locally, cannot provide

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