{"record":{"id":"8ac1892c7a47c47a","repo":"ipfs/kubo","slug":"only-sha2-255-32-is-allowed-with-cidv0","errorCode":null,"errorMessage":"only sha2-255-32 is allowed with CIDv0","messagePattern":"only sha2-255-32 is allowed with CIDv0","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/coreiface/options/block.go","lineNumber":130,"sourceCode":"\t\t\tformat = \"dag-cbor\"\n\t\t}\n\n\t\t// Set code based on name passed as \"format\"\n\t\tcode, err := codeFromName(format)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tsettings.CidPrefix.Codec = uint64(code)\n\n\t\t// If CIDv0, ensure all parameters are compatible\n\t\t// (in theory go-cid would validate this anyway, but we want to provide better errors)\n\t\tpref := settings.CidPrefix\n\t\tif pref.Version == 0 {\n\t\t\tif pref.Codec != uint64(mc.DagPb) {\n\t\t\t\treturn fmt.Errorf(\"only dag-pb is allowed with CIDv0\")\n\t\t\t}\n\t\t\tif pref.MhType != mh.SHA2_256 || (pref.MhLength != -1 && pref.MhLength != 32) {\n\t\t\t\treturn fmt.Errorf(\"only sha2-255-32 is allowed with CIDv0\")\n\t\t\t}\n\t\t}\n\n\t\treturn nil\n\t}\n}\n\n// Hash is an option for Block.Put which specifies the multihash settings to use\n// when hashing the object. Default is mh.SHA2_256 (0x12).\n// If mhLen is set to -1, default length for the hash will be used\nfunc (blockOpts) Hash(mhType uint64, mhLen int) BlockPutOption {\n\treturn func(settings *BlockPutSettings) error {\n\t\tsettings.CidPrefix.MhType = mhType\n\t\tsettings.CidPrefix.MhLength = mhLen\n\t\treturn nil\n\t}\n}\n","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreiface/options/block.go#L112-L148","documentation":"CIDv0 requires the multihash to be sha2-256 with the default 32-byte length. When a block put's CID prefix requests version 0 with any other hash function or a non-default length, this validator in core/coreiface/options/block.go rejects the settings before the block is written. (Note the message's typo 'sha2-255-32' — it means sha2-256 with length 32.)","triggerScenarios":"Calling `api.Block().Put` with options that set cid-version=0 together with a different multihash type (e.g. blake2b-256, sha3-256) or a custom mhLength (not -1 and not 32), e.g. `ipfs block put --cid-version=0 --mhtype=sha3-256` or `--mh-length=16`.","commonSituations":"CLI users combining `--mhtype` with CIDv0 on block put; scripts that hardened hashing (sha3/blake2) but left legacy `--cid-version 0`; library users building options.CidPrefix with Version=0 and non-default MhType/MhLength.","solutions":["Use CIDv1 with the desired hash: drop `--cid-version 0` or set `--cid-version=1` so `--mhtype=sha3-256` etc. are accepted.","Or keep CIDv0 and use the default multihash: remove `--mhtype`/`--mh-length` overrides (sha2-256, length 32).","Programmatically, when pref.Version == 0 set pref.MhType = mh.SHA2_256 and pref.MhLength = -1 (or 32), or bump the prefix to version 1."],"exampleFix":"// before (CLI)\nipfs block put --cid-version=0 --mhtype=sha3-256 data.bin\n// after\nipfs block put --cid-version=1 --mhtype=sha3-256 data.bin","handlingStrategy":"validation","validationCode":"func mhValidForV0(pref cid.Prefix) error {\n    if pref.Version == 0 && (pref.MhType != mh.SHA2_256 || (pref.MhLength != -1 && pref.MhLength != 32)) {\n        return errors.New(\"CIDv0 requires sha2-256 with 32-byte digest; use --cid-version=1\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"err := api.Block().Put(ctx, data, opts...)\nif err != nil && strings.Contains(err.Error(), \"sha2-255-32 is allowed with CIDv0\") {\n    // retry with CIDv1 to allow the custom multihash\n    opts = append(opts, options.BlockPut.CidVersion(1))\n    _, err = api.Block().Put(ctx, data, opts...)\n}","preventionTips":["Use sha2-256 (default mhtype) whenever CIDv0 is requested","Omit --mhtype/--mh-length overrides on legacy CIDv0 block puts","Prefer CIDv1 for any non-default multihash (sha3, blake2b, truncated digests)","Add a pre-flight settings check mirroring options/block.go validation in tooling"],"tags":["block","cid","cidv0","multihash","sha2-256","validation"],"backgroundTag":"cidv0-multihash-mismatch","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"}