{"record":{"id":"a2afcaa90291a96a","repo":"ipfs/kubo","slug":"failed-to-initialize-mfs-root-from-s-stored-at-s","errorCode":null,"errorMessage":"failed to initialize MFS root from %s stored at %s: %w. If corrupted, use 'ipfs files chroot' to reset (see --help)","messagePattern":"failed to initialize MFS root from (.+?) stored at (.+?): %w\\. If corrupted, use 'ipfs files chroot' to reset \\(see --help\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/node/core.go","lineNumber":289,"sourceCode":"\t\t}\n\t\tmfsOpts, err := cfg.Import.MFSRootOptions()\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to build MFS options from Import config: %w\", err)\n\t\t}\n\n\t\t// Keep dag here an online (network-backed) DAGService. \"ipfs files cp\n\t\t// /ipfs/<cid> /path\" stores a lazy pointer: only the referenced root is\n\t\t// fetched, and its children are pulled from the network on demand when\n\t\t// the tree is later traversed (\"files ls -l\", or \"stat\"/\"read\" of a\n\t\t// subpath). Do NOT swap in an offline/local-only DAGService to avoid an\n\t\t// under-lock bitswap hang, that turns those lazy lookups into \"block not\n\t\t// found locally\" errors. The GC-vs-MFS wedge that tempts that change\n\t\t// (ipfs/kubo#10842) is fixed on the GC side instead: MFS mutations hold\n\t\t// the pin lock and GC snapshots the MFS root under the GC lock, so live\n\t\t// MFS blocks are never collected out from under an in-flight write.\n\t\troot, err := mfs.NewRoot(ctx, dag, nd, pf, prov, mfsOpts...)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to initialize MFS root from %s stored at %s: %w. \"+\n\t\t\t\t\"If corrupted, use 'ipfs files chroot' to reset (see --help)\", nd.Cid(), FilesRootDatastoreKey, err)\n\t\t}\n\n\t\tlc.Append(fx.Hook{\n\t\t\tOnStop: func(ctx context.Context) error {\n\t\t\t\treturn shutdown.CloseWithCtx(ctx, \"mfs-root\", root.Close)\n\t\t\t},\n\t\t})\n\n\t\treturn root, err\n\t}\n}\n","sourceCodeStart":271,"sourceCodeEnd":302,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/node/core.go#L271-L302","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run `ipfs files chroot /` (see `ipfs files chroot --help`) to reset the MFS root to a new empty directory","Run `ipfs repo fsck`/`ipfs datastore verify` style diagnostics to assess datastore damage and restore from backup if needed","If blocks are missing but recoverable, re-add or re-fetch the content, then retry daemon start"],"exampleFix":"// before\nipfs daemon\n// Error: failed to initialize MFS root from <cid> stored at /local/filesroot: ...\n// after\nipfs files chroot /\nipfs daemon","handlingStrategy":"validation","validationCode":"// Before starting the daemon, verify the MFS root resolves\nrootCID, err := node.Repo.Datastore().Get(ctx, ds.NewKey(\"/local/filesroot\"))\nif err != nil {\n\t// no MFS root yet; `ipfs files chroot /` will create one\n\t_ = err\n}\n_ = rootCID","typeGuard":null,"tryCatchPattern":"if _, err := mfs.NewRoot(ctx, dag, nd, pf, prov, opts...); err != nil {\n\tvar bstoreErr *blockstore.ErrNotFound\n\tif errors.As(err, &bstoreErr) {\n\t\t// corrupted/missing root: reset MFS root\n\t\t// ipfs files chroot /\n\t}\n\treturn fmt.Errorf(\"failed to initialize MFS root: %w\", err)\n}","preventionTips":["Avoid manual edits to the datastore under /local/filesroot","Take repo backups before datastore migrations","Run ipfs repo gc only via supported CLI flows","After disk errors, verify the repo before restarting the daemon"],"tags":["mfs","datastore","corruption","startup"],"backgroundTag":"mfs-root-corrupted","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"}