larksuite/cli · error

%s contains unknown field %q

Error message

%s contains unknown field %q

What it means

Object shape validation: the supplied JSON object contains a key that is not declared in the shape and the shape disallows additional properties (AdditionalProperties=false). The binder rejects unknown keys to prevent silently ignored input.

Source

Thrown at shortcuts/common/typed_binder.go:503

	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
			}
		}
		return nil
	default:
		return fmt.Errorf("%s uses unsupported shape %T", path, shape)
	}
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Remove the unknown key or fix its spelling to match a declared field.
2. Run schema/--help to list the exact accepted field names.
3. Check for API-version drift: the field may have been renamed upstream.
4. If the object should accept arbitrary keys, the shape's AdditionalProperties must allow it — that is a metadata concern, not a caller flag.

Example fix

// before
lark-cli shortcut demo --card '{"card_id":"vc_1","tittle":"Hi"}'
// error: card contains unknown field "tittle"

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

allowed='{"card_id":true,"title":true}'
echo "$payload" | jq -e --argjson ok "$allowed" \
  'to_entries | map(.key) - ($ok | keys) | length == 0' >/dev/null || {
  echo "payload contains unknown fields" >&2; exit 2
}

func onlyKnownFields(obj map[string]any, allowed map[string]bool) []string {
    var unknown []string
    for k := range obj {
        if !allowed[k] { unknown = append(unknown, k) }
    }
    return unknown
}

err := cmd.Run()
var valErr *errs.ValidationError
if errors.As(err, &valErr) {
    var unknErr interface{ UnwrapKey() string }
    if strings.Contains(valErr.Error(), "unknown field") {
        // extract the key from the message, drop or rename it, retry
    }
    _ = unknErr
}

When it happens

Trigger: Passing an object with a typo'd or extra key to an object-typed flag whose shape is closed — e.g. --card '{"tittle":"x"}' or an extra legacy key no longer in the schema.

Common situations: Typo in field names; API version drift where a field was renamed or removed upstream; payloads copied from another endpoint with overlapping but different schemas; snake_case vs camelCase mistakes.

Related errors

• %s must be a boolean
• %s must be an integer
• %s must be a number
• %s must be an array
• %s must be an object

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