ipfs/kubo · error

%s and %s options are not compatible

Error message

%s and %s options are not compatible

What it means

`--only-hash` computes the CID without storing any blocks, while `--to-files` links the added content into MFS, which requires stored blocks. The two are contradictory, so kubo rejects the invocation up front.

Source

Thrown at core/commands/add.go:442

			fastProvideRoot = false
			fastProvideDAG = false
		}

		// Storing optional mode or mtime (UnixFS 1.5) requires root block
		// to always be 'dag-pb' and not 'raw'. Below adjusts raw-leaves setting, if possible.
		if preserveMode || preserveMtime || mode != 0 || mtime != 0 {
			// Error if --raw-leaves flag was explicitly passed by the user.
			// (let user make a decision to manually disable it and retry)
			if rbset && rawblks {
				return fmt.Errorf("%s can't be used with UnixFS metadata like mode or modification time", rawLeavesOptionName)
			}
			// No explicit preference from user, disable raw-leaves and continue
			rbset = true
			rawblks = false
		}

		if onlyHash && toFilesSet {
			return fmt.Errorf("%s and %s options are not compatible", onlyHashOptionName, toFilesOptionName)
		}
		if !dopin && pinNameSet {
			return fmt.Errorf("%s option requires %s to be set", pinNameOptionName, pinOptionName)
		}
		if wrap && toFilesSet {
			return fmt.Errorf("%s and %s options are not compatible", wrapOptionName, toFilesOptionName)
		}

		hashFunCode, ok := mh.Names[strings.ToLower(hashFunStr)]
		if !ok {
			return fmt.Errorf("unrecognized hash function: %q", strings.ToLower(hashFunStr))
		}

		enc, err := cmdenv.GetCidEncoder(req)
		if err != nil {
			return err
		}

View on GitHub (pinned to 329838acdf)

Solutions

1. Remove --only-hash if the file should land in MFS
2. Remove --to-files if only the CID is needed
3. Split into two calls: --only-hash for the CID, then a real add with --to-files

Example fix

// before
ipfs add --only-hash --to-files=/big-file big.bin
// after
ipfs add --to-files=/big-file big.bin

if onlyHash && toFiles != "" {
  return errors.New("--only-hash is incompatible with --to-files")
}

When it happens

Trigger: `ipfs add --only-hash --to-files=/foo file`; RPC add with HashOnly=true and ToFiles set; wrapper scripts that append --to-files to a shared command line also using --only-hash.

Common situations: Dry-run CID computation in a wrapper that unconditionally passes --to-files; users expecting --only-hash to populate MFS.

Related errors

• paths must not be empty
• paths must start with a leading slash
• invalid configuration profile: %s
• inline-limit %d exceeds maximum allowed size of %d bytes
• %s can't be used with UnixFS metadata like mode or modificat

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