What causes "%s option requires %s to be set" in ipfs/kubo?

Enable pinning: remove --pin=false or pass --pin=true

%s option requires %s to be set

Error message

%s option requires %s to be set

What it means

`--pin-name` names the pin created by `ipfs add`, so it is meaningless without pinning. When `--pin=false` is in effect while `--pin-name` is set, kubo rejects the command because there is no pin to attach the name to.

Source

Thrown at core/commands/add.go:445

		// 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
		}

		toadd := req.Files
		if wrap {
			toadd = files.NewSliceDirectory([]files.DirEntry{

View on GitHub (pinned to 329838acdf)

Solutions

Enable pinning: remove --pin=false or pass --pin=true
Remove --pin-name if the add should not be pinned
Pin by CID later: `ipfs pin add --name=... <cid>` after a non-pinned add

Example fix

// before
ipfs add --pin=false --pin-name=release ./dist
// after
ipfs add --pin=true --pin-name=release ./dist

Defensive patterns

Strategy: validation

Validate before calling

if pinName != "" && !pin {
  return errors.New("--pin-name requires --pin to be enabled")
}

Prevention

Only emit --pin-name when pinning is on
Default to pin=true unless the caller explicitly opts out

When it happens

Trigger: `ipfs add --pin=false --pin-name=backup file`; RPC add with Pin=false and PinName set; templates that always emit --pin-name while another flag disables pinning.

Common situations: Scripts parameterizing pin on/off but always passing a pin name; users disabling pinning to avoid pinset entries yet still naming the (nonexistent) pin.

Related errors

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