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

Pin.Ls's Type option only accepts the literal strings "direct", "indirect", "recursive", or "all" ("all" is the default). Any other string is rejected at option-construction time with this error, before any RPC call is made. It protects against typos and ensures the pin-type filter maps to a valid internal PinLsOption.

Source

Thrown at core/coreiface/options/pin.go:180

func (pinLsOpts) Indirect() PinLsOption {
	return Pin.Ls.pinType("indirect")
}

// Type is an option for Pin.Ls which will make it only return pins of the given
// type.
//
// Supported values:
//   - "direct" - directly pinned objects
//   - "recursive" - roots of recursive pins
//   - "indirect" - indirectly pinned objects (referenced by recursively pinned
//     objects)
//   - "all" - all pinned objects (default)
func (pinLsOpts) Type(typeStr string) (PinLsOption, error) {
	switch typeStr {
	case "all", "direct", "indirect", "recursive":
		return Pin.Ls.pinType(typeStr), nil
	default:
		return nil, fmt.Errorf("invalid type '%s', must be one of {direct, indirect, recursive, all}", typeStr)
	}
}

// pinType is an option for Pin.Ls which allows to specify which pin types should
// be returned
//
// Supported values:
//   - "direct" - directly pinned objects
//   - "recursive" - roots of recursive pins
//   - "indirect" - indirectly pinned objects (referenced by recursively pinned
//     objects)
//   - "all" - all pinned objects (default)
func (pinLsOpts) pinType(t string) PinLsOption {
	return func(settings *PinLsSettings) error {
		settings.Type = t
		return nil
	}
}

View on GitHub (pinned to 329838acdf)

Solutions

Use only one of "direct", "indirect", "recursive", "all" (lowercase, exact)
Trim and strings.ToLower user-supplied input before passing it to Type
Validate against the allowed set with a switch or slices.Contains before calling Type
Omit the Type option entirely to get the default "all" behavior

Example fix

// before
opt, err := options.Pin.Ls.Type("Recursive") // wrong case
// after
t := strings.ToLower(strings.TrimSpace(userInput))
if !slices.Contains([]string{"direct","indirect","recursive","all"}, t) {
    return fmt.Errorf("unsupported pin type: %s", t)
}
opt, err := options.Pin.Ls.Type(t)

Defensive patterns

Strategy: validation

Validate before calling

var validPinTypes = []string{"direct", "indirect", "recursive", "all"}
func validatePinType(s string) (string, error) {
    s = strings.ToLower(strings.TrimSpace(s))
    if !slices.Contains(validPinTypes, s) {
        return "", fmt.Errorf("pin type must be one of %v", validPinTypes)
    }
    return s, nil
}

Try / catch

opt, err := options.Pin.Ls.Type(t)
if err != nil {
    return fmt.Errorf("invalid pin ls type %q: %w", t, err)
}

Prevention

Always lowercase/trim user-supplied pin types before passing them to Type
Expose only the four valid values in UI dropdowns or CLI completions
Rely on the default "all" when no explicit filtering is needed

When it happens

Trigger: Calling pinLsOpts.Type("recursive ") (trailing whitespace), Type("Recursive") (wrong case), Type("all_pins") or any string outside the four accepted values while building options for Pin.Ls.

Common situations: Passing user input from a CLI flag or HTTP query parameter straight into Type without normalizing; case mismatches from a UI dropdown mapping; older code using pin-type names from a different API that differ slightly from kubo's set.

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/198156ce564df2a1. Report an issue: GitHub.