{"record":{"id":"9ff7f0ecc1b9623a","repo":"ipfs/kubo","slug":"only-dag-pb-is-allowed-with-cidv0","errorCode":null,"errorMessage":"only dag-pb is allowed with CIDv0","messagePattern":"only dag-pb is allowed with CIDv0","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/coreiface/options/block.go","lineNumber":127,"sourceCode":"\n\t\t// Fixup invalid name for dag-cbor (0x71)\n\t\tif format == \"cbor\" {\n\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","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreiface/options/block.go#L109-L145","documentation":"This validation error comes from block put option processing: CIDv0 is, by definition, always dag-pb with sha2-256, so when a caller supplies a CID prefix pinned to version 0 with a different multicodec, the settings validator rejects it. The library validates this explicitly (rather than relying on go-cid) to give a clearer, more actionable error than an opaque CID-encoding failure.","triggerScenarios":"Calling `api.Block().Put` (block put) with options that set `cid-version=0` together with a codec other than dag-pb, e.g. `ipfs block put --cid-codec=raw --cid-version=0`, or programmatically building options.CidPrefix with Version=0 and Codec != DagPb.","commonSituations":"CLI users combining `--cid-codec raw` (or raw-leaves/etc.) with the default/implicit CIDv0; scripts migrated from legacy block puts now passing an explicit codec; library users constructing a cid.Prefix manually with version 0 and a non-dag-pb codec.","solutions":["Drop `--cid-version 0` so the node picks CIDv1, which supports arbitrary codecs: `ipfs block put --cid-codec=raw` (defaults to v1).","Or keep CIDv0 and remove the codec override so the data is encoded as dag-pb.","Programmatically, set settings.CidPrefix.Codec = uint64(mc.DagPb) when Version == 0, or raise the prefix version to 1."],"exampleFix":"// before (CLI)\nipfs block put --cid-codec=raw --cid-version=0 data.bin\n// after\nipfs block put --cid-codec=raw --cid-version=1 data.bin","handlingStrategy":"validation","validationCode":"func cidPrefixValidForV0(pref cid.Prefix) error {\n    if pref.Version == 0 && pref.Codec != uint64(mc.DagPb) {\n        return errors.New(\"CIDv0 requires dag-pb codec; use --cid-version=1 for other codecs\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"err := api.Block().Put(ctx, data, opts...)\nif err != nil && strings.Contains(err.Error(), \"only dag-pb is allowed with CIDv0\") {\n    // rebuild options with CIDv1 or drop the codec override\n    opts = []options.BlockPutOption{options.BlockPut.Codec(\"raw\"), options.BlockPut.CidVersion(1)}\n    _, err = api.Block().Put(ctx, data, opts...)\n}","preventionTips":["Never combine --cid-codec (other than dag-pb) with --cid-version=0","Default to CIDv1 when using non-default codecs or hash functions","Validate cid.Prefix settings before calling Block().Put","Pin cid profiles in scripts so version/codec/hash stay consistent"],"tags":["block","cid","cidv0","dag-pb","validation"],"backgroundTag":"cidv0-codec-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"}