larksuite/cli · error

%s must contain at most %d characters

Error message

%s must contain at most %d characters

What it means

This error comes from the typed binder's JSON shape validation: a string field value exceeded the maxLength constraint declared by the field's schema. The binder walks the value against the compiled shape (validateJSONValueAgainstShape) and rejects the input before any API call is made. Length is measured in runes, not bytes, so multibyte characters count once each.

Source

Thrown at shortcuts/common/typed_binder.go:423

		expected, err := decodeJSONValidationValue(expectedJSON)
		if err != nil {
			return fmt.Errorf("%s has invalid const: %w", path, err)
		}
		if !reflect.DeepEqual(value, expected) {
			return fmt.Errorf("%s must equal %v", path, constraint.Value)
		}
		return nil
	case typedStringShape:
		text, ok := value.(string)
		if !ok {
			return fmt.Errorf("%s must be a string", path)
		}
		length := len([]rune(text))
		if constraint.MinLength != nil && length < *constraint.MinLength {
			return fmt.Errorf("%s must contain at least %d characters", path, *constraint.MinLength)
		}
		if constraint.MaxLength != nil && length > *constraint.MaxLength {
			return fmt.Errorf("%s must contain at most %d characters", path, *constraint.MaxLength)
		}
		if len(constraint.Enum) > 0 && !slices.Contains(constraint.Enum, text) {
			return fmt.Errorf("%s must be one of: %s", path, strings.Join(constraint.Enum, ", "))
		}
		return nil
	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)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Shorten the string value to at or below the maxLength reported in the error message
2. Check the field's schema via the command's `schema` output to confirm the exact limit
3. If the value is generated programmatically, truncate to the limit (rune-aware, not byte-aware)
4. If the limit appears wrong, verify you are on an up-to-date catalog (re-run the meta fetch / update the CLI)

Example fix

// before
name := strings.Repeat("a", 300)
call(field(name))
// after
if len([]rune(name)) > 255 {
    name = string([]rune(name)[:255])
}
call(field(name))

func ensureMaxRunes(s string, max int) error {
    if len([]rune(s)) > max {
        return fmt.Errorf("value too long: %d > %d", len([]rune(s)), max)
    }
    return nil
}

func isStringWithinLength(v any, max int) bool {
    s, ok := v.(string)
    return ok && len([]rune(s)) <= max
}

err := bind(field, value)
var verr *FieldValidationError
if errors.As(err, &verr) {
    fmt.Fprintf(os.Stderr, "fix input for %s: %v\n", verr.Field, err)
    os.Exit(2)
}

When it happens

Trigger: Calling a typed shortcut with a string argument/flag whose rune length exceeds the schema's maxLength (e.g. a 300-char value where the field allows 255); supplying an over-long string inside a nested object or array item validated by valueCompatibleWithShape.

Common situations: Pasting long descriptions, names, IDs or tokens into fields with fixed limits; generating test data that exceeds the documented limit; locale/emoji content inflating perceived-but-not-rune length; API limits tightened after a schema refresh.

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

• %s must be one of: %s
• Args field %s (--%s): InputField.Shape conflicts with schema
• Shape conflicts with schema constraints or nullable declarat
• schema tag must declare exactly one of required or optional
• schema contains blank or untrimmed token %q

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