ipfs/kubo · error

failed to build MFS options from Import config: %w

Error message

failed to build MFS options from Import config: %w

What it means

After loading the config, Kubo calls cfg.Import.MFSRootOptions() to translate the `Import` config section into MFS root options (e.g. CidV1 defaults, hash function, unixfs settings for MFS writes). If the configured values are invalid (unsupported CID version, unknown multihash, bad option combination), this constructor fails and the error is wrapped as "failed to build MFS options from Import config".

Source

Thrown at core/node/core.go:274

		// MFS (Mutable File System) provider integration: Only pass the provider
		// to MFS when the strategy includes "mfs". MFS will call StartProviding()
		// on every DAGService.Add() operation, which is sufficient for the "mfs"
		// strategy - it ensures all MFS content gets announced as it's added or
		// modified. For non-mfs strategies, we set provider to nil to avoid
		// unnecessary providing.
		strategyFlag := config.MustParseProvideStrategy(strategy)
		if strategyFlag&config.ProvideStrategyMFS == 0 {
			prov = nil
		}

		// Get configured settings from Import config
		cfg, err := repo.Config()
		if err != nil {
			return nil, fmt.Errorf("failed to get config: %w", err)
		}
		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)
		}

View on GitHub (pinned to 329838acdf)

Solutions

1. Read the wrapped cause at the end of the error message — it names the exact invalid Import key/value.
2. Inspect current values: `ipfs config Import` and compare against docs/config.md; reset to defaults with `ipfs config --json Import.CidVersion 0` (or remove the bad key).
3. Fix HashFunction to a supported multihash name, e.g. `ipfs config Import.HashFunction sha2-256`.
4. Use `ipfs config show | jq .Import` to confirm only documented keys exist, then restart the daemon.

Example fix

// before (config.json)
{"Import": {"CidVersion": 3, "HashFunction": "sha2-257"}}

// after
ipfs config --json Import.CidVersion 1
ipfs config Import.HashFunction sha2-256

// Validate Import config values before node startup
import "github.com/multiformats/go-multihash"
cfg, err := repo.Config()
if err != nil { return err }
if _, err := multihash.DecodeString(cfg.Import.HashFunction.WithDefault("sha2-256")); err != nil {
    return fmt.Errorf("Import.HashFunction invalid: %w", err)
}

// Unwrap and report the offending Import key
if mfsOpts, err := cfg.Import.MFSRootOptions(); err != nil {
    return fmt.Errorf("Import config rejected (check CidVersion/HashFunction values): %w", err)
}

When it happens

Trigger: Daemon startup with an invalid `Import` config section: e.g. `Import.CidVersion` set to an unsupported version, an invalid `Import.HashFunction` name, or MFSRootOptions rejecting the combination — the error message embeds the specific validation failure via %w.

Common situations: Following outdated blog posts that set Import keys that were renamed or removed; typos in hash function names (e.g. "sha2-256 " with whitespace); setting CidVersion to 3 or higher; copying config from another implementation with different option names.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Import.CidVersion must be 0 or 1, got %d
• Import.UnixFSFileMaxLinks must be positive, got %d
• Import.UnixFSDirectoryMaxLinks must be non-negative, got %d
• Import.BatchMaxNodes must be positive, got %d
• Import.BatchMaxSize must be positive, got %d

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