What causes "%s must contain at most %d items" in larksuite/cli?

Chunk the array into batches at or under the declared maximum and call the command once per batch.

%s must contain at most %d items

Error message

%s must contain at most %d items

What it means

Typed array shape validation: the supplied array has more items than the declared maxItems constraint.

Source

Thrown at shortcuts/common/typed_binder.go:477

			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)
		}
		fields := make(map[string]typedValueField, len(constraint.Fields))
		for _, field := range constraint.Fields {
			fields[field.Name] = field
			if field.Required {
				if _, exists := object[field.Name]; !exists {
					return fmt.Errorf("%s.%s is required", path, field.Name)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Chunk the array into batches at or under the declared maximum and call the command once per batch.
Cap or truncate the list before invocation.
Check --help/schema for the exact MaxItems for this field.
If batches must be sequential, add pagination logic in the calling script.

Example fix

// before
lark-cli shortcut demo --user-ids '[100 ids...]'
// error: user_ids must contain at most 50 items

// after
# chunk into groups of 50 and run per chunk
lark-cli shortcut demo --user-ids '[id1,...,id50]'
lark-cli shortcut demo --user-ids '[id51,...,id100]'

Defensive patterns

Strategy: validation

Validate before calling

const maxItems = 50
for i := 0; i < len(ids); i += maxItems {
    end := i + maxItems
    if end > len(ids) { end = len(ids) }
    chunk := ids[i:end]
    // invoke the command with chunk
}

Type guard

func hasMaxItems[T any](xs []T, n int) bool { return len(xs) <= n }

Try / catch

err := cmd.Run()
if err != nil && strings.Contains(err.Error(), "must contain at most") {
    // split the array into smaller batches and retry each batch
}

Prevention

Chunk bulk ID lists to the documented MaxItems before calling.
Look up the batch cap in --help/schema.
Never assume a batch limit; verify per command.
Test bulk scripts with an over-cap list.

When it happens

Trigger: Passing an array longer than MaxItems — commonly batching more than the declared cap of IDs into a single batch call, e.g. --user-ids with 100 entries where at most 50 are allowed.

Common situations: Bulk operations that concatenate all target IDs without chunking; upstream API batch-size limits; script changes that increased input volume.

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/5fc40d82530f3ca6. Report an issue: GitHub.