ipfs/kubo · error

invalid CID %q: %w

Error message

invalid CID %q: %w

What it means

`ipfs files chroot` parses its optional CID argument with cmdutils.CidFromArg; when parsing fails the underlying error is wrapped as `invalid CID %q: %w`. This means the string supplied as the new root is not a syntactically valid CID (bad multibase/encoding) or an unsupported codec/version.

Source

Thrown at core/commands/files.go:1746

	Extra:    CreateCmdExtras(SetDoesNotUseRepo(true)),
	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
		confirm, _ := req.Options[chrootConfirmOptionName].(bool)
		if !confirm {
			return errors.New("this is a potentially destructive operation; pass --confirm to proceed")
		}

		enc, err := cmdenv.GetCidEncoder(req)
		if err != nil {
			return err
		}

		// Determine new root CID
		var newRootCid cid.Cid
		if len(req.Arguments) > 0 {
			var err error
			newRootCid, err = cmdutils.CidFromArg(req.Arguments[0])
			if err != nil {
				return fmt.Errorf("invalid CID %q: %w", req.Arguments[0], err)
			}
		} else {
			// Default to empty directory
			newRootCid = ft.EmptyDirNode().Cid()
		}

		// Get config root to open repo directly
		cctx := env.(*oldcmds.Context)
		cfgRoot := cctx.ConfigRoot

		// Open repo directly (daemon must not be running)
		repo, err := fsrepo.Open(cfgRoot)
		if err != nil {
			return fmt.Errorf("opening repo (is the daemon running?): %w", err)
		}
		defer repo.Close()

		localDS := repo.Datastore()

View on GitHub (pinned to 329838acdf)

Solutions

1. Pass a valid, complete CID string (verify first with `ipfs cid <string>` or `ipfs cid format`).
2. Strip any `/ipfs/` prefix and pass only the CID itself.
3. Omit the argument entirely to reset the MFS root to the empty directory.

Example fix

// before
ipfs files chroot --confirm /ipfs/QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco
// after
ipfs files chroot --confirm QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco

ipfs cid format "$ARG" > /dev/null || { echo "not a valid CID: $ARG"; exit 2; }

func looksLikeCid(s string) bool { _, err := cid.Decode(s); return err == nil }

newRoot, err := cmdutils.CidFromArg(arg)
if err != nil {
    return fmt.Errorf("--%s must be a bare CID (no /ipfs/ prefix), got %q", flag, arg)
}

When it happens

Trigger: Passing a bare base58 string, a content hash, an IPFS path (`/ipfs/<cid>`), or a typo'd/truncated CID as the argument to `ipfs files chroot`; passing a CID of a codec that CidFromArg rejects.

Common situations: Copy-paste truncation of long CIDv1 strings; confusing a UnixFS path with a CID; using old base58 CIDv0 output where the tooling expects a full CIDv1 string, or vice versa.

Related errors

• inline-limit %d exceeds maximum allowed size of %d bytes
• invalid format string: %q
• cannot convert to CIDv0 with any codec other than dag-pb
• cannot convert to CIDv0 with any multibase other than the im
• invalid cid version: %q

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