larksuite/cli · error

%s must equal %v

Error message

%s must equal %v

What it means

A const-shape field must exactly equal (reflect.DeepEqual after JSON round-trip) the declared const value; any other value fails with this message showing the expected value. Thrown by validateJSONValueAgainstShape in the typedConstShape branch when DeepEqual fails.

Source

Thrown at shortcuts/common/typed_binder.go:410

			}
		}
		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 {
			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

View on GitHub (pinned to 7fd6ef3c07)

Solutions

  1. Set the field exactly to the value shown in the error message (or the schema's const declaration).
  2. Remove the field if your client library should inject the constant automatically.
  3. If the const itself is outdated (API moved on), update the compiled shape definition.

Example fix

// before
params.Set("api_version", "2.x") // const: "2.0"

// after
params.Set("api_version", "2.0")
Defensive patterns

Strategy: validation

Validate before calling

if !reflect.DeepEqual(candidate, expectedConst) { return fmt.Errorf("value must equal %v", expectedConst) }

Type guard

func equalsConst(v, want any) bool { return reflect.DeepEqual(v, want) }

Try / catch

if err := binder.Set("api_version", v); err != nil {
    if strings.Contains(err.Error(), "must equal") {
        return fmt.Errorf("use the exact documented constant: %w", err)
    }
    return err
}

Prevention

When it happens

Trigger: Supplying any value other than the schema's fixed const for a field, e.g. sending "v2" where const is "v1", or a value that differs in Go type after JSON decode (2 vs 2.0).

Common situations: API version fields, enum-like constants, or method/version discriminators hardcoded in the schema; developers invent their own value or copy an example from a different endpoint version.

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/66c3b1f5700c38e0. Report an issue: GitHub.