{"record":{"id":"d6293d41072018aa","repo":"ipfs/kubo","slug":"nocopy-option-requires-raw-leaves-to-be-enable","errorCode":null,"errorMessage":"nocopy option requires '--raw-leaves' to be enabled as well","messagePattern":"nocopy option requires '--raw-leaves' to be enabled as well","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/coreiface/options/unixfs.go","lineNumber":119,"sourceCode":"\t\tPreserveMtime:       false,\n\t\tMode:                0,\n\t\tMtime:               time.Time{},\n\t\tIncludeEmptyDirs:    true, // default: include empty directories\n\t\tIncludeEmptyDirsSet: false,\n\t}\n\n\tfor _, opt := range opts {\n\t\terr := opt(options)\n\t\tif err != nil {\n\t\t\treturn nil, cid.Prefix{}, err\n\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 {","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/coreiface/options/unixfs.go#L101-L137","documentation":"The Unixfs Add NoCopy option (used for the filestore) requires raw blocks (RawLeaves), because --nocopy must reference original file bytes rather than wrapping them in UnixFS nodes. If RawLeaves was not explicitly set by the caller (RawLeavesSet is false), the library silently satisfies the constraint by enabling RawLeaves; the error is only returned when the caller explicitly set RawLeaves to false, which is an unsatisfiable combination.","triggerScenarios":"Calling UnixfsAddOptions with NoCopy=true and RawLeaves=false where RawLeaves was explicitly set to false via options.Unixfs.RawLeaves(false) (so RawLeavesSet is true). NoCopy=true without touching RawLeaves does NOT error — the library auto-enables RawLeaves.","commonSituations":"Config files where nocopy is on but raw-leaves is explicitly off; generic add-option builders that always call RawLeaves(false) as a default; users following older documentation that did not tie nocopy to raw-leaves.","solutions":["Remove the explicit RawLeaves(false) option so the library can auto-enable raw leaves for nocopy","Explicitly pass options.Unixfs.RawLeaves(true) together with NoCopy(true)","Set only NoCopy(true) and let the library satisfy the mandatory raw-leaves constraint itself","Update config templates so raw-leaves is never explicitly disabled when nocopy is enabled"],"exampleFix":"// before\nopts, err := options.Unixfs.Add().NoCopy(true).RawLeaves(false) // unsatisfiable\n// after\nopts, err := options.Unixfs.Add().NoCopy(true).RawLeaves(true)","handlingStrategy":"validation","validationCode":"func checkNocopyOptions(noCopy, rawLeaves, rawLeavesSet bool) error {\n    if noCopy && rawLeavesSet && !rawLeaves {\n        return errors.New(\"nocopy requires raw-leaves to be enabled\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"opts, _, err := options.Unixfs.AddOptions(...)\nif err != nil {\n    if strings.Contains(err.Error(), \"nocopy\") {\n        return fmt.Errorf(\"filestore config conflict: %w\", err)\n    }\n    return err\n}","preventionTips":["Never explicitly set RawLeaves(false) when NoCopy(true) is in use; omit the option instead","In config merging, drop an explicit raw-leaves=false when nocopy=true","Document the nocopy->raw-leaves dependency wherever add options are exposed to users"],"tags":["go","ipfs","unixfs","filestore","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"}