ipfs/kubo · error

cannot change CID format of the MFS root; use 'ipfs config I

Error message

cannot change CID format of the MFS root; use 'ipfs config Import.CidVersion' and 'ipfs config Import.HashFunction' instead

What it means

The `ipfs files chcid` command refuses to run when the target path is the MFS root '/'. The root's CID format cannot be changed in place via chcid; instead the caller must change the node-level import settings (Import.CidVersion / Import.HashFunction) or replace the root with `ipfs files chmod`-style root replacement. It is a precondition check on the path argument.

Source

Thrown at core/commands/files.go:1317

`,
	},
	Arguments: []cmds.Argument{
		cmds.StringArg("path", true, false, "Path to change (must not be '/')."),
	},
	Options: []cmds.Option{
		cidVersionOption,
		hashOption,
	},
	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
		nd, err := cmdenv.GetNode(env)
		if err != nil {
			return err
		}
		defer mfsPinLock(nd, req.Context).Unlock(req.Context)

		path := req.Arguments[0]
		if path == "/" {
			return fmt.Errorf("cannot change CID format of the MFS root; " +
				"use 'ipfs config Import.CidVersion' and 'ipfs config Import.HashFunction' instead")
		}

		flush, _ := req.Options[filesFlushOptionName].(bool)

		// Note: files chcid is for explicitly changing CID format, so we don't
		// fall back to Import config here. If no options are provided, it does nothing.
		prefix, err := getPrefix(req, nil)
		if err != nil {
			return err
		}

		if err := updatePath(nd.FilesRoot, path, prefix); err != nil {
			return err
		}
		if flush {
			if _, err = mfs.FlushPath(req.Context, nd.FilesRoot, path); err != nil {
				return err

View on GitHub (pinned to 329838acdf)

Solutions

1. Target a subdirectory instead of '/', e.g. `ipfs files chcid /mydir --cid-version 1`.
2. To change the root's CID format, set `ipfs config Import.CidVersion` / `Import.HashFunction` and rebuild MFS, or copy contents into a new directory and replace the root.

When it happens

Trigger: Thrown at core/commands/files.go:1317 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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