larksuite/cli · error

%svalue %v is below minimum %v

Error message

%svalue %v is below minimum %v

What it means

Schema validation error raised by collectSchemaErrors in the sheets shortcut flag validator. When a flag value parsed as a number (float64) is smaller than the JSON-schema `minimum` bound declared for that field, the validator records this intermediate error. It is later wrapped into a typed flag validation error with a --print-schema hint by validateFlagAgainstSchema.

Source

Thrown at shortcuts/sheets/flag_schema_validate.go:375

	if schema == nil || c.full() {
		return
	}
	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

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Raise the flag value to at least the schema minimum shown by --print-schema.
2. Check the field's expected range in the schema and clamp/validate inputs before invoking the command.
3. If the value comes from upstream output, guard sentinel values like -1 or 0 before passing them through.

Example fix

// before
lark-cli sheets batch --values '{"start_row": 0}'  // minimum is 1
// after
lark-cli sheets batch --values '{"start_row": 1}'

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

function isNumberAtLeast(v: unknown, min: number): v is number {
  return typeof v === "number" && Number.isFinite(v) && v >= min;
}

When it happens

Trigger: Passing a --flag value that JSON-parses to a number below the schema's `minimum` for that property, e.g. a row index or limit field declared `minimum: 1` receiving 0 or a negative number.

Common situations: Using 0-based thinking for a 1-based field; computing an offset or count that underflows; templating a value from another command output that yields -1 or 0 for 'not found'.

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 above maximum %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/4fbfd17c5b92d86f. Report an issue: GitHub.