invalid type '%s', must be one of {direct, indirect, recursi

Error message

invalid type '%s', must be one of {direct, indirect, recursive, all}

What it means

`ipfs pin ls` accepts a `--type` option restricted to direct, indirect, recursive, or all. The value is converted with `pin.StringToMode`; when it does not match any known mode, the command returns this formatted error naming the invalid value.

Source

Thrown at core/commands/pin/pin.go:486

		}

		if n.Pinning == nil {
			return fmt.Errorf("pinning service not available")
		}

		typeStr, _ := req.Options[pinTypeOptionName].(string)
		stream, _ := req.Options[pinStreamOptionName].(bool)
		displayNames, _ := req.Options[pinNamesOptionName].(bool)
		name, _ := req.Options[pinNameOptionName].(string)

		// Validate name filter
		if err := cmdutils.ValidatePinName(name); err != nil {
			return err
		}

		mode, ok := pin.StringToMode(typeStr)
		if !ok {
			return fmt.Errorf("invalid type '%s', must be one of {direct, indirect, recursive, all}", typeStr)
		}

		// For backward compatibility, we accumulate the pins in the same output type as before.
		var emit func(PinLsOutputWrapper) error
		lgcList := map[string]PinLsType{}
		if !stream {
			emit = func(v PinLsOutputWrapper) error {
				lgcList[v.PinLsObject.Cid] = PinLsType{Type: v.PinLsObject.Type, Name: v.PinLsObject.Name}
				return nil
			}
		} else {
			emit = func(v PinLsOutputWrapper) error {
				return res.Emit(v)
			}
		}

		if len(req.Arguments) > 0 {
			err = pinLsKeys(req, mode, displayNames || name != "", n.Pinning, api, emit)

View on GitHub (pinned to 329838acdf)

Solutions

Use exactly one of: direct, indirect, recursive, all (lowercase).
Default to `--type=recursive` (the effective default) if unsure.
Validate the value in scripts before passing it to the command.
For status of all pins including through-relations, use `--type=all`.

Example fix

// before
client.Request("pin/ls").Option("type", "Recursive").Send(ctx)
// after
client.Request("pin/ls").Option("type", "recursive").Send(ctx)

Defensive patterns

Strategy: validation

Validate before calling

var validTypes = map[string]bool{"direct": true, "indirect": true, "recursive": true, "all": true}
if !validTypes[typeFlag] {
    return fmt.Errorf("invalid pin type %q: use direct|indirect|recursive|all", typeFlag)
}

Prevention

Always use lowercase pin type names
Centralize pin-type constants in scripts
Never feed user input straight into --type

When it happens

Trigger: `ipfs pin ls --type <bad>` with values like `recursive-`, `Recursive` (case-sensitive), `tree`, or a typo such as `recursve`; also RPC calls to `pin/ls` with an invalid `type` option.

Common situations: Typoed type values in scripts; assuming case-insensitivity; copying flags from older documentation or other tools that use different pin-type vocabularies.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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