--%s implies --%s=false and cannot be combined with --%s=tru

Error message

--%s implies --%s=false and cannot be combined with --%s=true; please drop one of them

What it means

`ipfs dag import --local-only` skips the network entirely, so a partial CAR cannot guarantee a complete DAG to pin; kubo therefore forces pin-roots off. If the caller explicitly sets --pin-roots=true together with --local-only, the command rejects the contradictory options with this error.

Source

Thrown at core/commands/dag/import.go:64

	api, err = api.WithOptions(options.Api.Offline(true))
	if err != nil {
		return err
	}

	pinRootsVal, pinRootsSet := req.Options[pinRootsOptionName].(bool)
	localOnly, _ := req.Options[localOnlyOptionName].(bool)

	// --pin-roots defaults to true; the default is applied here (not via
	// .WithDefault) so we can tell apart "user explicitly passed true" from
	// "no value provided".
	doPinRoots := true
	if pinRootsSet {
		doPinRoots = pinRootsVal
	}

	if localOnly {
		if pinRootsSet && pinRootsVal {
			return fmt.Errorf("--%s implies --%s=false and cannot be combined with --%s=true; please drop one of them", localOnlyOptionName, pinRootsOptionName, pinRootsOptionName)
		}
		// --local-only implies --pin-roots=false: a partial CAR has no full DAG to pin.
		doPinRoots = false
	}
	fastProvideRoot, fastProvideRootSet := req.Options[fastProvideRootOptionName].(bool)
	fastProvideDAG, fastProvideDAGSet := req.Options[fastProvideDAGOptionName].(bool)
	fastProvideWait, fastProvideWaitSet := req.Options[fastProvideWaitOptionName].(bool)

	fastProvideRoot = config.ResolveBoolFromConfig(fastProvideRoot, fastProvideRootSet, cfg.Import.FastProvideRoot, config.DefaultFastProvideRoot)
	fastProvideDAG = config.ResolveBoolFromConfig(fastProvideDAG, fastProvideDAGSet, cfg.Import.FastProvideDAG, config.DefaultFastProvideDAG)
	fastProvideWait = config.ResolveBoolFromConfig(fastProvideWait, fastProvideWaitSet, cfg.Import.FastProvideWait, config.DefaultFastProvideWait)

	// grab a pinlock ( which doubles as a GC lock ) so that regardless of the
	// size of the streamed-in cars nothing will disappear on us before we had
	// a chance to roots that may show up at the very end
	// This is especially important for use cases like dagger:
	//    ipfs dag import $( ... | ipfs-dagger --stdout=carfifos )
	//

View on GitHub (pinned to 329838acdf)

Solutions

Drop --pin-roots=true; --local-only already implies --pin-roots=false
Remove --local-only if you actually want the full DAG fetched and roots pinned
Pin explicitly later once the complete DAG is available (e.g. via `ipfs pin add`)

Example fix

// before
ipfs dag import --local-only --pin-roots=true data.car
// after
ipfs dag import --local-only data.car

Defensive patterns

Strategy: validation

Validate before calling

// reject conflicting flags before invoking the CLI
if localOnly && pinRootsExplicitTrue {
    return fmt.Errorf("--local-only cannot be combined with --pin-roots=true")
}

Prevention

When using --local-only, omit --pin-roots entirely
Pin explicitly afterwards if you need pins from offline imports
Review script flags when copying between online/offline import flows

When it happens

Trigger: Running `ipfs dag import --local-only --pin-roots=true carfile.car`. The error fires only when pin-roots is explicitly set true; an implicit default is fine because local-only silently implies pin-roots=false.

Common situations: Scripts combining offline import with pinning expectations; users assuming --pin-roots is required to keep imported data; copying flags from non-local import examples.

Related errors

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