What causes "%s must be null" in larksuite/cli?

Set the field's value to nil (or omit it entirely) instead of a placeholder value.

%s must be null

Error message

%s must be null

What it means

Typed-binder shape validation: a value bound to a nullable-only slot (typedNullShape) is not JSON null. Fires when user input supplies a non-null value where the schema only permits null.

Source

Thrown at shortcuts/common/typed_binder.go:397

		return typedFieldValidation(field, "%v", err).WithCause(err)
	}
	return nil
}

func validateJSONValueAgainstShape(value any, shape typedValueShape, path string) error {
	switch constraint := shape.(type) {
	case anyJSONShape:
		return nil
	case typedOneOfShape:
		for _, variant := range constraint.Variants {
			if err := validateJSONValueAgainstShape(value, variant, path); err == nil {
				return nil
			}
		}
		return fmt.Errorf("%s does not match any allowed shape", path)
	case typedNullShape:
		if value != nil {
			return fmt.Errorf("%s must be null", path)
		}
		return nil
	case typedConstShape:
		expectedJSON, err := json.Marshal(constraint.Value)
		if err != nil {
			return fmt.Errorf("%s has invalid const: %w", path, err)
		}
		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 {

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Set the field's value to nil (or omit it entirely) instead of a placeholder value.
Remove the field from the request if you did not intend to clear it.
If the field should accept real values, fix its shape constraint — it is likely declared null by mistake.

Example fix

// before
params.Set("description", "") // null-typed field

// after
params.Set("description", nil) // or don't set the field

Defensive patterns

Strategy: validation

Validate before calling

if v != nil { return fmt.Errorf("field must be nil or omitted") }

Type guard

func isNil(v any) bool {
    if v == nil { return true }
    rv := reflect.ValueOf(v)
    switch rv.Kind() {
    case reflect.Ptr, reflect.Map, reflect.Slice, reflect.Chan, reflect.Func, reflect.Interface:
        return rv.IsNil()
    }
    return false
}

Try / catch

if err := binder.Set("description", val); err != nil {
    if strings.Contains(err.Error(), "must be null") {
        return fmt.Errorf("description only accepts null (to clear); got %v", val)
    }
    return err
}

Prevention

Use nil, not "" or 0, for clear-value semantics.
Omit optional fields entirely when you have no value.
Check the field's shape before writing clear/update logic.

When it happens

Trigger: Passing any non-nil value (string, number, object, even empty string or 0) to a field whose compiled shape is typedNullShape.

Common situations: APIs that use explicit null fields to clear a value; developers mistakenly send a placeholder like "" or "none" instead of nil, or a code path fails to omit the field and inserts a default value.

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

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