{"record":{"id":"be114c25c2d32cef","repo":"ipfs/kubo","slug":"unknown-cid-version-d","errorCode":null,"errorMessage":"unknown CID version: %d","messagePattern":"unknown CID version: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/coreiface/options/unixfs.go","lineNumber":134,"sourceCode":"\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\n\t}\n\n\t// cidV1 -> raw blocks (by default)\n\tif options.CidVersion > 0 && !options.RawLeavesSet {","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreiface/options/unixfs.go#L116-L152","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use CidVersion(0) or CidVersion(1); CIDv0 requires the sha2-256 hash function (pair it with Hash only with MHashSha256)","Omit the option entirely (or pass -1) to get the library default for the given hash/settings","Audit the call site for a variable holding a codec/multihash code being fed to CidVersion; only 0, 1, -1 are valid inputs"],"exampleFix":"// before\nopts, err := options.Unixfs.Add(options.Unixfs.CidVersion(2))\n// error: unknown CID version: 2\n\n// after\nopts, err := options.Unixfs.Add(options.Unixfs.CidVersion(1))","handlingStrategy":"validation","validationCode":"func validCidVersion(v int) bool {\n    return v == 0 || v == 1 || v == -1\n}\n// call site\nif !validCidVersion(ver) {\n    return fmt.Errorf(\"cid version must be 0, 1, or -1, got %d\", ver)\n}\nopts, err := options.Unixfs.Add(options.Unixfs.CidVersion(ver))","typeGuard":"func isSupportedCidVersion(n int) bool {\n    switch n {\n    case -1, 0, 1:\n        return true\n    }\n    return false\n}","tryCatchPattern":"opts, err := options.Unixfs.Add(opts...)\nif err != nil {\n    var pfxErr error\n    if strings.Contains(err.Error(), \"unknown CID version\") {\n        // fall back to default version\n        opts, pfxErr = options.Unixfs.Add()\n        if pfxErr == nil {\n            return addWith(opts)\n        }\n    }\n    return fmt.Errorf(\"unixfs add options: %w\", err)\n}","preventionTips":["Only pass the literals 0, 1, or -1 to CidVersion — no other CID version exists","Never feed CID codec or multihash codes into CidVersion; they are different number spaces","Remember CIDv0 requires sha2-256: pair CidVersion(0) with the default hash only","Omit the option entirely when you want the library default"],"tags":["cid","unixfs","validation","options"],"backgroundTag":"invalid-cid-version","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"}