{"record":{"id":"4852e3f6f42b90c4","repo":"ipfs/kubo","slug":"failed-to-build-mfs-options-from-import-config-w","errorCode":null,"errorMessage":"failed to build MFS options from Import config: %w","messagePattern":"failed to build MFS options from Import config: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/node/core.go","lineNumber":274,"sourceCode":"\t\t// MFS (Mutable File System) provider integration: Only pass the provider\n\t\t// to MFS when the strategy includes \"mfs\". MFS will call StartProviding()\n\t\t// on every DAGService.Add() operation, which is sufficient for the \"mfs\"\n\t\t// strategy - it ensures all MFS content gets announced as it's added or\n\t\t// modified. For non-mfs strategies, we set provider to nil to avoid\n\t\t// unnecessary providing.\n\t\tstrategyFlag := config.MustParseProvideStrategy(strategy)\n\t\tif strategyFlag&config.ProvideStrategyMFS == 0 {\n\t\t\tprov = nil\n\t\t}\n\n\t\t// Get configured settings from Import config\n\t\tcfg, err := repo.Config()\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to get config: %w\", err)\n\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","sourceCodeStart":256,"sourceCodeEnd":292,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/node/core.go#L256-L292","documentation":"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\".","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped cause at the end of the error message — it names the exact invalid Import key/value.","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).","Fix HashFunction to a supported multihash name, e.g. `ipfs config Import.HashFunction sha2-256`.","Use `ipfs config show | jq .Import` to confirm only documented keys exist, then restart the daemon."],"exampleFix":"// before (config.json)\n{\"Import\": {\"CidVersion\": 3, \"HashFunction\": \"sha2-257\"}}\n\n// after\nipfs config --json Import.CidVersion 1\nipfs config Import.HashFunction sha2-256","handlingStrategy":"validation","validationCode":"// Validate Import config values before node startup\nimport \"github.com/multiformats/go-multihash\"\ncfg, err := repo.Config()\nif err != nil { return err }\nif _, err := multihash.DecodeString(cfg.Import.HashFunction.WithDefault(\"sha2-256\")); err != nil {\n    return fmt.Errorf(\"Import.HashFunction invalid: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"// Unwrap and report the offending Import key\nif mfsOpts, err := cfg.Import.MFSRootOptions(); err != nil {\n    return fmt.Errorf(\"Import config rejected (check CidVersion/HashFunction values): %w\", err)\n}","preventionTips":["Only set Import keys documented in docs/config.md; verify with `ipfs config show | jq .Import`.","Use supported hash names (e.g. sha2-256) and CID versions (0 or 1) only.","After upgrading Kubo, diff your config against the new defaults and remove stale keys.","Test config changes in a throwaway IPFS_PATH before production restart."],"tags":["config","import","mfs","validation","startup"],"backgroundTag":"invalid-config-value","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"}