ipfs/kubo · error

unknown CID version: %d

Error message

unknown CID version: %d

What it means

UnixfsAddOptions validates the CID version requested for `ipfs add`-style operations. Only CIDv0 (which mandates sha2-256), CIDv1, and -1 (the 'unset/default' sentinel, normalized to 1) are supported; any other integer has no defined meaning in the UnixFS add path, so the library rejects it instead of guessing.

Source

Thrown at core/coreiface/options/unixfs.go:134

	if options.NoCopy && !options.RawLeaves {
		// fixed?
		if options.RawLeavesSet {
			return nil, cid.Prefix{}, fmt.Errorf("nocopy option requires '--raw-leaves' to be enabled as well")
		}

		// No, satisfy mandatory constraint.
		options.RawLeaves = true
	}

	// (hash != "sha2-256") -> CIDv1
	if options.MhType != mh.SHA2_256 {
		switch options.CidVersion {
		case 0:
			return nil, cid.Prefix{}, errors.New("CIDv0 only supports sha2-256")
		case 1, -1:
			options.CidVersion = 1
		default:
			return nil, cid.Prefix{}, fmt.Errorf("unknown CID version: %d", options.CidVersion)
		}
	} else {
		if options.CidVersion < 0 {
			// Default to CIDv0
			options.CidVersion = 0
		}
	}

	if !options.Mtime.IsZero() && options.PreserveMtime {
		options.PreserveMtime = false
	}

	if options.Mode != 0 && options.PreserveMode {
		options.PreserveMode = false
	}

	// cidV1 -> raw blocks (by default)
	if options.CidVersion > 0 && !options.RawLeavesSet {

View on GitHub (pinned to 329838acdf)

Solutions

1. Use CidVersion(0) or CidVersion(1); CIDv0 requires the sha2-256 hash function (pair it with Hash only with MHashSha256)
2. Omit the option entirely (or pass -1) to get the library default for the given hash/settings
3. Audit the call site for a variable holding a codec/multihash code being fed to CidVersion; only 0, 1, -1 are valid inputs

Example fix

// before
opts, err := options.Unixfs.Add(options.Unixfs.CidVersion(2))
// error: unknown CID version: 2

// after
opts, err := options.Unixfs.Add(options.Unixfs.CidVersion(1))

func validCidVersion(v int) bool {
    return v == 0 || v == 1 || v == -1
}
// call site
if !validCidVersion(ver) {
    return fmt.Errorf("cid version must be 0, 1, or -1, got %d", ver)
}
opts, err := options.Unixfs.Add(options.Unixfs.CidVersion(ver))

func isSupportedCidVersion(n int) bool {
    switch n {
    case -1, 0, 1:
        return true
    }
    return false
}

opts, err := options.Unixfs.Add(opts...)
if err != nil {
    var pfxErr error
    if strings.Contains(err.Error(), "unknown CID version") {
        // fall back to default version
        opts, pfxErr = options.Unixfs.Add()
        if pfxErr == nil {
            return addWith(opts)
        }
    }
    return fmt.Errorf("unixfs add options: %w", err)
}

When it happens

Trigger: Calling options.Unixfs.Add.CidVersion(n) (or the --cid-version CLI/RPC flag) with a value other than 0, 1, or -1 — e.g. CidVersion(2) or CidVersion(3) — then passing the options to coreapi Add. The error fires inside UnixfsAddOptions before any block is written.

Common situations: Copy-pasted code assuming arbitrary CID versions exist (only 0 and 1 are defined by the multiformats CID spec); looping over versions programmatically and overshooting; mistaking CID codec values (e.g. dag-pb 0x70) for version numbers; passing a parsed CID's codec or multihash code into CidVersion by mistake.

Related errors

• CIDv0 only supports sha2-256
• HAMT fanout must be a power of 2, between 8 and 1024 (got %d
• mtime nanoseconds must be in range [1, 999999999]
• Import.CidVersion must be 0 or 1, got %d
• Import.UnixFSFileMaxLinks must be positive, got %d

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