What causes "%s must be one of: %s" in larksuite/cli?

Use one of the values listed in the error message exactly (match case and spelling)

must be one of

Error message

%s must be one of: %s

What it means

The typed binder rejected a string value that is not a member of the field's enum constraint. When a schema declares an enumerated set of allowed strings, any other string is refused locally before the API call. The error lists every accepted value so the caller can pick a valid one.

Solutions

Use one of the values listed in the error message exactly (match case and spelling)
Inspect the field's allowed values with the command's `schema` output
Normalize casing/whitespace of user-supplied input before binding
If a needed value is missing from the enum, update the CLI/catalog metadata to the latest schema

Example fix

// before
status := "In Progress"
call(field(status))
// after
status := "in_progress" // must be one of the schema's enum values
call(field(status))

Defensive patterns

Strategy: validation

Validate before calling

func ensureEnum(s string, allowed []string) error {
    if !slices.Contains(allowed, s) {
        return fmt.Errorf("%q not in %v", s, allowed)
    }
    return nil
}

Type guard

func isAllowedString(v any, allowed ...string) bool {
    s, ok := v.(string)
    return ok && slices.Contains(allowed, s)
}

Try / catch

if err := bind(field, status); err != nil {
    if strings.Contains(err.Error(), "must be one of:") {
        return fmt.Errorf("invalid %s: %w (see `lark ... schema` for allowed values)", field, err)
    }
    return err
}

Prevention

Define allowed values as Go constants or an enum type instead of raw strings
Run the command with `schema` first when exploring a new field
Normalize case/whitespace of user input against the enum list
Copy values from `schema` output rather than from memory or docs

When it happens

Trigger: Passing a string flag/argument whose schema has constraint.Enum set with a value not in that set (case differences and whitespace count as mismatches); setting a nested object field to a non-enum string validated by valueCompatibleWithShape.

Common situations: Typing 'Active' instead of 'active'; using a human label ('In Progress') instead of the API token ('in_progress'); stale documentation from an older enum set; translating values from another API.

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 larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/20c888ae5188b513. Report an issue: GitHub.

Appendix: source

Thrown at shortcuts/common/typed_binder.go:426

		}
		if !reflect.DeepEqual(value, expected) {
			return fmt.Errorf("%s must equal %v", path, constraint.Value)
		}
		return nil
	case typedStringShape:
		text, ok := value.(string)
		if !ok {
			return fmt.Errorf("%s must be a string", path)
		}
		length := len([]rune(text))
		if constraint.MinLength != nil && length < *constraint.MinLength {
			return fmt.Errorf("%s must contain at least %d characters", path, *constraint.MinLength)
		}
		if constraint.MaxLength != nil && length > *constraint.MaxLength {
			return fmt.Errorf("%s must contain at most %d characters", path, *constraint.MaxLength)
		}
		if len(constraint.Enum) > 0 && !slices.Contains(constraint.Enum, text) {
			return fmt.Errorf("%s must be one of: %s", path, strings.Join(constraint.Enum, ", "))
		}
		return nil
	case typedBooleanShape:
		boolean, ok := value.(bool)
		if !ok {
			return fmt.Errorf("%s must be a boolean", path)
		}
		if len(constraint.Enum) > 0 && !slices.Contains(constraint.Enum, boolean) {
			return fmt.Errorf("%s has an unsupported boolean value", path)
		}
		return nil
	case typedIntegerShape:
		number, ok := validationInteger(value)
		if !ok {
			return fmt.Errorf("%s must be an integer", path)
		}
		if constraint.Minimum != nil && number < *constraint.Minimum {
			return fmt.Errorf("%s must be at least %d", path, *constraint.Minimum)

View on GitHub (pinned to 7fd6ef3c07)