What causes "%v cannot be represented as %s" in larksuite/cli?

Replace negative values with the API's accepted non-negative equivalent (omit the field or use the documented sentinel)

%v cannot be represented as %s

Error message

%v cannot be represented as %s

What it means

During integer conversion, a signed source value that is negative or exceeds the destination unsigned type's range cannot be represented; convertReflectValue rejects it with '%v cannot be represented as %s' instead of silently wrapping around.

Source

Thrown at shortcuts/common/typed_binder.go:239

		for i := 0; i < rawValue.Len(); i++ {
			value, err := convertReflectValue(rawValue.Index(i).Interface(), target.Elem())
			if err != nil {
				return nil, err
			}
			result.Index(i).Set(reflect.ValueOf(value))
		}
		if target.Kind() == reflect.Array {
			array := reflect.New(target).Elem()
			reflect.Copy(array, result)
			return array.Interface(), nil
		}
		return result.Convert(target).Interface(), nil
	}
	if rawValue.Type().ConvertibleTo(target) {
		converted := reflect.New(target).Elem()
		if isSignedIntegerKind(rawValue.Kind()) && isUnsignedIntegerKind(target.Kind()) {
			if rawValue.Int() < 0 || converted.OverflowUint(uint64(rawValue.Int())) {
				return nil, fmt.Errorf("%v cannot be represented as %s", raw, target)
			}
		}
		if isSignedIntegerKind(rawValue.Kind()) && isSignedIntegerKind(target.Kind()) && converted.OverflowInt(rawValue.Int()) {
			return nil, fmt.Errorf("%v overflows %s", raw, target)
		}
		if isUnsignedIntegerKind(rawValue.Kind()) && isUnsignedIntegerKind(target.Kind()) && converted.OverflowUint(rawValue.Uint()) {
			return nil, fmt.Errorf("%v overflows %s", raw, target)
		}
		return rawValue.Convert(target).Interface(), nil
	}
	encoded, err := json.Marshal(raw)
	if err != nil {
		return nil, err
	}
	value := reflect.New(target)
	if err := json.Unmarshal(encoded, value.Interface()); err != nil {
		return nil, err
	}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Replace negative values with the API's accepted non-negative equivalent (omit the field or use the documented sentinel)
Clamp values to the target's max (e.g. 255 for uint8) or widen the field type in the shortcut definition
Verify with schema output which integer width the field declares

Example fix

// before
--limit -1  // into uint32
// after
--limit 4294967295  // or omit if the API treats absence as unlimited

Defensive patterns

Strategy: validation

Validate before calling

const n = Number(raw); if (!Number.isInteger(n) || n < 0 || n > 4294967295) throw new Error('out of uint32 range')

Type guard

func fitsUint(v int64, bits int) bool { return v >= 0 && v <= int64(uint64(1)<<uint(bits)-1) }

Try / catch

if strings.Contains(err.Error(), "cannot be represented as") { /* replace negative sentinel or clamp to the type max */ }

Prevention

Never pass -1 as an ID/limit to unsigned fields; omit or use documented sentinels
Check the declared integer width via schema output
Clamp or validate numeric inputs at script boundaries

When it happens

Trigger: Passing a negative number to a uint-typed field, or a value above the unsigned max of the target width (e.g. 300 into uint8, -1 into uint64).

Common situations: IDs or sizes copied as signed values including sentinels like -1 ('unlimited'); JSON numbers exceeding narrow Go integer widths; type narrowing after schema change.

Related errors

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