nocopy option requires '--raw-leaves' to be enabled as well

Error message

nocopy option requires '--raw-leaves' to be enabled as well

What it means

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.

Source

Thrown at core/coreiface/options/unixfs.go:119

		PreserveMtime:       false,
		Mode:                0,
		Mtime:               time.Time{},
		IncludeEmptyDirs:    true, // default: include empty directories
		IncludeEmptyDirsSet: false,
	}

	for _, opt := range opts {
		err := opt(options)
		if err != nil {
			return nil, cid.Prefix{}, err
		}
	}

	// nocopy -> rawblocks
	if options.NoCopy && !options.RawLeaves {
		// fixed?
		if options.RawLeavesSet {
			return nil, cid.Prefix{}, fmt.Errorf("nocopy option requires '--raw-leaves' to be enabled as well")
		}

		// No, satisfy mandatory constraint.
		options.RawLeaves = true
	}

	// (hash != "sha2-256") -> CIDv1
	if options.MhType != mh.SHA2_256 {
		switch options.CidVersion {
		case 0:
			return nil, cid.Prefix{}, errors.New("CIDv0 only supports sha2-256")
		case 1, -1:
			options.CidVersion = 1
		default:
			return nil, cid.Prefix{}, fmt.Errorf("unknown CID version: %d", options.CidVersion)
		}
	} else {
		if options.CidVersion < 0 {

View on GitHub (pinned to 329838acdf)

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

Example fix

// before
opts, err := options.Unixfs.Add().NoCopy(true).RawLeaves(false) // unsatisfiable
// after
opts, err := options.Unixfs.Add().NoCopy(true).RawLeaves(true)

Defensive patterns

Strategy: validation

Validate before calling

func checkNocopyOptions(noCopy, rawLeaves, rawLeavesSet bool) error {
    if noCopy && rawLeavesSet && !rawLeaves {
        return errors.New("nocopy requires raw-leaves to be enabled")
    }
    return nil
}

Try / catch

opts, _, err := options.Unixfs.AddOptions(...)
if err != nil {
    if strings.Contains(err.Error(), "nocopy") {
        return fmt.Errorf("filestore config conflict: %w", err)
    }
    return err
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/d6293d41072018aa. Report an issue: GitHub.