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

Lower the value to at most the maximum shown in the error message

%s must be at most %d

Error message

%s must be at most %d

What it means

Typed integer shape validation: the supplied integer exceeds the field's declared maximum. Fires during JSON value validation of compiled Args fields.

Source

Thrown at shortcuts/common/typed_binder.go:447

	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)
		}
		if constraint.Maximum != nil && number > *constraint.Maximum {
			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)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Lower the value to at most the maximum shown in the error message
Clamp before the call: if v > max { v = max } or chunk the work into multiple calls
If the intent is 'as much as possible', query `schema` for the max and use it
Validate user input at the entry point of your script

Example fix

// before
pageSize := 1000
// after
const maxPageSize = 100
if pageSize > maxPageSize {
    pageSize = maxPageSize
}

Defensive patterns

Strategy: validation

Validate before calling

func clampMax(v int, max int) int {
    if v > max {
        return max
    }
    return v
} // or chunk requests when a single capped value is insufficient

Type guard

func isWithinMax(v int, max int) bool { return v <= max }

Try / catch

if err := bind(field, n); err != nil {
    if strings.Contains(err.Error(), "must be at most") {
        return fmt.Errorf("field %s exceeds maximum; cap or split the request: %w", field, err)
    }
    return err
}

Prevention

Cap user-supplied sizes at the schema maximum before binding
Paginate/split work instead of exceeding batch-size limits
Read the exact limit from `schema` rather than hardcoding guesses
Validate that defaults imported from other systems respect this API's caps

When it happens

Trigger: Passing page_size or batch size above the API limit (e.g. 500 where max is 100); an ID or timestamp exceeding an allowed range; unbounded user input mapped to a capped field.

Common situations: User-supplied sizes without clamping; defaults from other APIs with higher limits; accumulating values (timeouts in seconds) that grew past the cap.

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