What causes "%s must be an array" in larksuite/cli?

Wrap the value as a JSON array: '["a","b"]' with proper shell quoting.

%s must be an array

Error message

%s must be an array

What it means

Array shape validation: a field declared as a typed array received something that is not a JSON array after decoding. The binder's type assertion to []any fails and it reports the field path with this message.

Source

Thrown at shortcuts/common/typed_binder.go:471

	case typedNumberShape:
		number, ok := validationNumber(value)
		if !ok {
			return fmt.Errorf("%s must be a number", path)
		}
		if len(constraint.Enum) > 0 && !slices.Contains(constraint.Enum, number) {
			return fmt.Errorf("%s has an unsupported number value", path)
		}
		if constraint.Minimum != nil && number < *constraint.Minimum {
			return fmt.Errorf("%s must be at least %v", path, *constraint.Minimum)
		}
		if constraint.Maximum != nil && number > *constraint.Maximum {
			return fmt.Errorf("%s must be at most %v", path, *constraint.Maximum)
		}
		return nil
	case typedArrayShape:
		items, ok := value.([]any)
		if !ok {
			return fmt.Errorf("%s must be an array", path)
		}
		if constraint.MinItems != nil && len(items) < *constraint.MinItems {
			return fmt.Errorf("%s must contain at least %d items", path, *constraint.MinItems)
		}
		if constraint.MaxItems != nil && len(items) > *constraint.MaxItems {
			return fmt.Errorf("%s must contain at most %d items", path, *constraint.MaxItems)
		}
		for i, item := range items {
			if err := validateJSONValueAgainstShape(item, constraint.Items, fmt.Sprintf("%s[%d]", path, i)); err != nil {
				return err
			}
		}
		return nil
	case typedObjectShape:
		object, ok := value.(map[string]any)
		if !ok {
			return fmt.Errorf("%s must be an object", path)
		}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Wrap the value as a JSON array: '["a","b"]' with proper shell quoting.
Check --help or schema to confirm the field is an array and its item shape.
Quote the argument so the shell does not eat the brackets.
If building the value programmatically, marshal a slice/JSON array, not a single value.

Example fix

// before
lark-cli shortcut demo --member-ids ou_x,ou_y
// error: member_ids must be an array

// after
lark-cli shortcut demo --member-ids '["ou_x","ou_y"]'

Defensive patterns

Strategy: type-guard

Validate before calling

value='$1'
if ! echo "$value" | jq -e 'type=="array"' >/dev/null; then
  echo "expected a JSON array" >&2; exit 2
fi

Type guard

func isJSONArray(raw string) bool {
    var v []any
    return json.Unmarshal([]byte(raw), &v) == nil
}

Try / catch

err := cmd.Run()
var valErr *errs.ValidationError
if errors.As(err, &valErr) && strings.Contains(valErr.Error(), "must be an array") {
    // wrap the input in a JSON array and retry
}

Prevention

Always quote JSON arguments single-quoted to protect brackets.
Validate flag payloads with jq before invoking the CLI.
Check the field's item shape in schema output.
Marshal real slices when building flags programmatically.

When it happens

Trigger: Passing a scalar, object, or comma-separated string where a JSON array flag is expected — e.g. --member-ids u123 (bare string) instead of '["u123"]'.

Common situations: Users unfamiliar with JSON-typed flags passing bare values or space-separated lists; shell quoting stripping brackets so the payload becomes malformed; YAML/config files supplying a string for a list field.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/c278c95d7f545dd6. Report an issue: GitHub.