What causes "%s.%s is required" in larksuite/cli?

Add the missing key with a valid value to the JSON object.

%s.%s is required

Error message

%s.%s is required

What it means

Typed object shape validation: a required field (Name) is absent from the supplied JSON object. Path identifies the parent object and missing field name.

Source

Thrown at shortcuts/common/typed_binder.go:495

			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
			}
		}
		return nil
	case typedObjectShape:
		object, ok := value.(map[string]any)
		if !ok {
			return fmt.Errorf("%s must be an object", path)
		}
		fields := make(map[string]typedValueField, len(constraint.Fields))
		for _, field := range constraint.Fields {
			fields[field.Name] = field
			if field.Required {
				if _, exists := object[field.Name]; !exists {
					return fmt.Errorf("%s.%s is required", path, field.Name)
				}
			}
		}
		for name, item := range object {
			field, exists := fields[name]
			if !exists {
				if !constraint.AdditionalProperties {
					return fmt.Errorf("%s contains unknown field %q", path, name)
				}
				if constraint.AdditionalPropertiesShape != nil {
					if err := validateJSONValueAgainstShape(item, constraint.AdditionalPropertiesShape, path+"."+name); err != nil {
						return err
					}
				}
				continue
			}
			if err := validateJSONValueAgainstShape(item, field.Shape, path+"."+name); err != nil {
				return err

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Add the missing key with a valid value to the JSON object.
Check schema/--help for the object's field list and which are required.
Compare your payload against the field names in the error path (nested objects produce dotted paths).
If the field is genuinely optional upstream, verify the shape is generated from current metadata.

Example fix

// before
lark-cli shortcut demo --card '{"title":"Hello"}'
// error: card.card_id is required

// after
lark-cli shortcut demo --card '{"card_id":"vc_123","title":"Hello"}'

Defensive patterns

Strategy: validation

Validate before calling

required=(card_id)
for key in "${required[@]}"; do
  echo "$payload" | jq -e --arg k "$key" 'has($k)' >/dev/null || {
    echo "missing required field: $k" >&2; exit 2
  }
done

Type guard

func hasRequired(obj map[string]any, keys ...string) bool {
    for _, k := range keys {
        if _, ok := obj[k]; !ok { return false }
    }
    return true
}

Try / catch

err := cmd.Run()
var valErr *errs.ValidationError
if errors.As(err, &valErr) && strings.Contains(valErr.Error(), " is required") {
    // parse the dotted path from the message, add the field, retry
}

Prevention

List required fields with schema/--help before constructing payloads.
Keep payload builders in one place so required keys are never dropped.
Diff your payload keys against the error's dotted path for nested objects.
When renaming fields in scripts, grep for the old name in payloads.

When it happens

Trigger: Supplying a JSON object for an object-typed flag while omitting a field marked Required in its shape — e.g. --card '{"title":"x"}' when card_id is required.

Common situations: Partial updates sent as full objects without required keys; renaming a field in a script while the shape still expects the old name; copying examples that omit required members; nested objects where an inner object has required fields.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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