ipfs/kubo · error

invalid cid version: %q

Error message

invalid cid version: %q

What it means

Fired by the `ipfs cid` command when the --cid-ver (or equivalent) option is set to a string other than "", "0", or "1". It is a validation guard over the user-supplied version argument: only CIDv0 and CIDv1 conversions are supported, so any other value (typo like "v1", "2", "3") is rejected before any conversion runs.

Source

Thrown at core/commands/cid.go:104

		} // otherwise, leave it as 0 (not a valid IPLD codec)

		switch verStr {
		case "":
			if baseStr != "" {
				opts.verConv = toCidV1
			}
		case "0":
			if opts.newCodec != 0 && opts.newCodec != cid.DagProtobuf {
				return errors.New("cannot convert to CIDv0 with any codec other than dag-pb")
			}
			if baseStr != "" && baseStr != "base58btc" {
				return errors.New("cannot convert to CIDv0 with any multibase other than the implicit base58btc")
			}
			opts.verConv = toCidV0
		case "1":
			opts.verConv = toCidV1
		default:
			return fmt.Errorf("invalid cid version: %q", verStr)
		}

		if baseStr != "" {
			encoder, err := mbase.EncoderByName(baseStr)
			if err != nil {
				return err
			}
			opts.newBase = encoder.Encoding()
		} else {
			opts.newBase = mbase.Encoding(-1)
		}

		return emitCids(req, resp, opts)
	},
	PostRun: cmds.PostRunMap{
		cmds.CLI: streamResult(func(v any, out io.Writer) nonFatalError {
			r := v.(*CidFormatRes)
			if r.ErrorMsg != "" {

View on GitHub (pinned to 329838acdf)

Solutions

1. Use exactly 0 or 1 (or omit the flag to keep the input version)
2. Validate the version value in scripts before passing it
3. Use CIDv1 (there is no CIDv2); for new hash functions stick with version 1

Example fix

// before
ipfs cid format --cid-ver=v1 <cid>
// after
ipfs cid format --cid-ver=1 <cid>

validVersions := map[string]struct{}{"": {}, "0": {}, "1": {}}
if _, ok := validVersions[ver]; !ok {
    return fmt.Errorf("invalid cid version: %q", ver)
}

if err != nil && strings.Contains(err.Error(), "invalid cid version") {
    // sanitize --cid-ver input and retry
}

When it happens

Trigger: Passing --cid-ver=2, --cid-ver=v1, or any typo'd version value to `ipfs cid format`.

Common situations: Assuming CIDv2 or 'v1' prefixed values are accepted; scripts parameterizing the version with an unvalidated value; future-version guesswork.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

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 %q: %w

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