larksuite/cli · error

%svalue %v is above maximum %v

Error message

%svalue %v is above maximum %v

What it means

Schema validation error from collectSchemaErrors: a numeric flag value exceeds the JSON-schema `maximum` bound. The validator only applies this when the value is a number; the intermediate error is wrapped by validateFlagAgainstSchema into a typed flag validation error with a --print-schema hint.

Source

Thrown at shortcuts/sheets/flag_schema_validate.go:378

	if value == nil && schema.Nullable {
		return
	}

	if schema.Type != "" {
		if !matchesJSONType(value, schema.Type) {
			c.add(&typeMismatchError{path: path, expected: schema.Type, got: jsType(value), enum: schema.Enum, description: schema.Description})
			return // wrong container type — descending would cascade nonsense.
		}
	}

	// Numeric bounds — only checked when value is a number (type mismatch
	// already reported above). Apply to both `number` and `integer` types.
	if num, ok := value.(float64); ok {
		if schema.Minimum != nil && num < *schema.Minimum {
			c.add(fmt.Errorf("%svalue %v is below minimum %v", pathPrefix(path), num, *schema.Minimum)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
		}
		if schema.Maximum != nil && num > *schema.Maximum {
			c.add(fmt.Errorf("%svalue %v is above maximum %v", pathPrefix(path), num, *schema.Maximum)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
		}
	}

	// Array length bounds — only checked when value is an array.
	if arr, ok := value.([]interface{}); ok {
		if schema.MinItems != nil && len(arr) < *schema.MinItems {
			c.add(fmt.Errorf("%sarray has %d items, minimum is %d", pathPrefix(path), len(arr), *schema.MinItems)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
		}
		if schema.MaxItems != nil && len(arr) > *schema.MaxItems {
			c.add(fmt.Errorf("%sarray has %d items, maximum is %d", pathPrefix(path), len(arr), *schema.MaxItems)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
		}
	}

	if len(schema.Enum) > 0 {
		matched := false
		for _, allowed := range schema.Enum {
			if jsonEqual(allowed, value) {
				matched = true

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Lower the value to at most the schema maximum shown by --print-schema.
2. Split oversized requests (e.g. chunk a large batch into schema-compliant batches).
3. Validate/ clamp numeric inputs against the schema bounds before invoking.

Example fix

// before
lark-cli sheets batch --limit 10000  // maximum is 5000
// after
lark-cli sheets batch --limit 5000

const max = 5000; // from schema maximum
if (typeof value === "number" && value > max) {
  throw new Error(`value must be <= ${max}, got ${value}`);
}

function isNumberAtMost(v: unknown, max: number): v is number {
  return typeof v === "number" && Number.isFinite(v) && v <= max;
}

When it happens

Trigger: Passing a --flag number larger than the schema's declared `maximum`, e.g. a limit/capacity field with `maximum: 5000` receiving 10000.

Common situations: Requesting page sizes or batch counts above the API cap; using absolute counts where a bounded range is required; porting values from a different API version with looser limits.

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

• %svalue %v is below minimum %v
• +csv-get truncated the requested range at {source_range}; na
• Multiple sheets matched; pass --sheet-id or --sheet-name
• %sarray has %d items, minimum is %d
• %sarray has %d items, maximum is %d

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