What causes "CIDv0 only supports sha2-256" in ipfs/kubo?

Remove the explicit CidVersion(0) when using a non-sha2-256 hash so the library upgrades to CIDv1 automatically

CIDv0 only supports sha2-256

Error message

CIDv0 only supports sha2-256

What it means

CIDv0 can only be built with the sha2-256 multihash; any other multihash type requires CIDv1. UnixfsAddOptions enforces this when the caller sets MhType to something other than mh.SHA2_256 while CidVersion is 0, returning this error. If CidVersion is 1 or the unset sentinel (-1), the library silently upgrades the version to 1.

Source

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

		}
	}

	// nocopy -> rawblocks
	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

View on GitHub (pinned to 329838acdf)

Solutions

Remove the explicit CidVersion(0) when using a non-sha2-256 hash so the library upgrades to CIDv1 automatically
Explicitly set options.Unixfs.CidVersion(1) when choosing a non-sha2-256 multihash
Keep MhType at mh.SHA2_256 (default) if CIDv0 output is required
Pre-validate the hash/version combination in config parsing before calling the API

Example fix

// before
opts, err := options.Unixfs.Add().Hash("blake3").CidVersion(0) // invalid combo
// after
opts, err := options.Unixfs.Add().Hash("blake3").CidVersion(1)

Defensive patterns

Strategy: validation

Validate before calling

func checkCidCompat(cidVersion int, mhType uint64) error {
    if mhType != mh.SHA2_256 && cidVersion == 0 {
        return errors.New("CIDv0 only supports sha2-256; use CidVersion(1)")
    }
    return nil
}

Try / catch

opts, prefix, err := options.Unixfs.AddOptions(...)
if err != nil {
    if strings.Contains(err.Error(), "CIDv0") {
        return fmt.Errorf("hash/CID version mismatch: %w", err)
    }
    return err
}

Prevention

Only pin CidVersion(0) when the multihash is sha2-256
Let the library auto-upgrade to CIDv1 by not setting CidVersion when using alternate hashes
Centralize CID-version/hash decisions in one config layer so the combination is checked in one place

When it happens

Trigger: Calling UnixfsAddOptions with options.Unixfs.Hash(mh.BLAKE3 or similar non-sha2-256 multihash) combined with options.Unixfs.CidVersion(0). Using a non-sha2-256 hash without setting CidVersion does not error — the version auto-upgrades to 1.

Common situations: Config files pinning CIDv0 for compatibility with old tooling while also requesting a newer hash function; users wanting CIDv0 short strings but a different hash; option builders that default CidVersion(0) for backwards compatibility while allowing hash overrides.

Related errors

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