{"record":{"id":"15b109d684e6f593","repo":"ipfs/kubo","slug":"cidv0-only-supports-sha2-256","errorCode":null,"errorMessage":"CIDv0 only supports sha2-256","messagePattern":"CIDv0 only supports sha2-256","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/coreiface/options/unixfs.go","lineNumber":130,"sourceCode":"\t\t}\n\t}\n\n\t// nocopy -> rawblocks\n\tif options.NoCopy && !options.RawLeaves {\n\t\t// fixed?\n\t\tif options.RawLeavesSet {\n\t\t\treturn nil, cid.Prefix{}, fmt.Errorf(\"nocopy option requires '--raw-leaves' to be enabled as well\")\n\t\t}\n\n\t\t// No, satisfy mandatory constraint.\n\t\toptions.RawLeaves = true\n\t}\n\n\t// (hash != \"sha2-256\") -> CIDv1\n\tif options.MhType != mh.SHA2_256 {\n\t\tswitch options.CidVersion {\n\t\tcase 0:\n\t\t\treturn nil, cid.Prefix{}, errors.New(\"CIDv0 only supports sha2-256\")\n\t\tcase 1, -1:\n\t\t\toptions.CidVersion = 1\n\t\tdefault:\n\t\t\treturn nil, cid.Prefix{}, fmt.Errorf(\"unknown CID version: %d\", options.CidVersion)\n\t\t}\n\t} else {\n\t\tif options.CidVersion < 0 {\n\t\t\t// Default to CIDv0\n\t\t\toptions.CidVersion = 0\n\t\t}\n\t}\n\n\tif !options.Mtime.IsZero() && options.PreserveMtime {\n\t\toptions.PreserveMtime = false\n\t}\n\n\tif options.Mode != 0 && options.PreserveMode {\n\t\toptions.PreserveMode = false","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreiface/options/unixfs.go#L112-L148","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nopts, err := options.Unixfs.Add().Hash(\"blake3\").CidVersion(0) // invalid combo\n// after\nopts, err := options.Unixfs.Add().Hash(\"blake3\").CidVersion(1)","handlingStrategy":"validation","validationCode":"func checkCidCompat(cidVersion int, mhType uint64) error {\n    if mhType != mh.SHA2_256 && cidVersion == 0 {\n        return errors.New(\"CIDv0 only supports sha2-256; use CidVersion(1)\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"opts, prefix, err := options.Unixfs.AddOptions(...)\nif err != nil {\n    if strings.Contains(err.Error(), \"CIDv0\") {\n        return fmt.Errorf(\"hash/CID version mismatch: %w\", err)\n    }\n    return err\n}","preventionTips":["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"],"tags":["go","ipfs","cid","unixfs","options"],"backgroundTag":"incompatible-options","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}