What causes "%s must be at most %v" in larksuite/cli?

Lower the value to at most the bound shown in the message.

%s must be at most %v

Error message

%s must be at most %v

What it means

Typed number shape validation: a numeric value exceeds the field's declared maximum (floating-point variant). Part of validateJSONValueAgainstShape for number-typed fields.

Source

Thrown at shortcuts/common/typed_binder.go:465

			return fmt.Errorf("%s must be at most %d", path, *constraint.Maximum)
		}
		if len(constraint.Enum) > 0 && !slices.Contains(constraint.Enum, number) {
			return fmt.Errorf("%s has an unsupported integer value", path)
		}
		return nil
	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
			}
		}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Lower the value to at most the bound shown in the message.
Run --help or schema for the command to see the allowed range.
If you need more items, paginate with page_token instead of raising page_size.
Verify the constraint in the upstream OpenAPI metadata if you think the cap is stale.

Example fix

// before
lark-cli shortcut demo --page-size 500
// error: page_size must be at most 50

// after
lark-cli shortcut demo --page-size 50

Defensive patterns

Strategy: validation

Validate before calling

const maxSize = 50
if pageSize > maxSize {
    return fmt.Errorf("page_size must be at most %d", maxSize)
}
// proceed with the command invocation

Type guard

func inRangeInt(v, min, max int64) bool { return v >= min && v <= max }

Prevention

Look up the documented maximum in --help/schema before calling.
Chunk work instead of inflating limit/page_size values.
Never copy limits from other APIs without checking this CLI's schema.
Handle pagination tokens rather than oversized pages.

When it happens

Trigger: Passing a numeric flag/JSON value greater than the shape's Maximum, e.g. --page-size 100 when the shape allows at most 50.

Common situations: Assuming an API accepts large page sizes or limits, migrating from another API with higher caps, or computing values (counts, timeouts) that overflow the declared range.

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