What causes "expected list, got %T" in larksuite/cli?

Pass a JSON array: --ids '["a","b"]'

expected list, got %T

Error message

expected list, got %T

What it means

convertReflectValue, when the target type is a slice or array, requires the raw compiled value to itself be an array/slice (as produced by JSON decoding or repeated flags). Any other Go kind (string, map, number) yields 'expected list, got %T'.

Source

Thrown at shortcuts/common/typed_binder.go:215

	if target == jsonRawMessageType {
		encoded, err := json.Marshal(raw)
		if err != nil {
			return nil, err
		}
		return json.RawMessage(encoded), nil
	}
	if target.Kind() == reflect.Pointer {
		value, err := convertReflectValue(raw, target.Elem())
		if err != nil {
			return nil, err
		}
		pointer := reflect.New(target.Elem())
		pointer.Elem().Set(reflect.ValueOf(value))
		return pointer.Interface(), nil
	}
	if target.Kind() == reflect.Array || target.Kind() == reflect.Slice {
		if rawValue.Kind() != reflect.Array && rawValue.Kind() != reflect.Slice {
			return nil, fmt.Errorf("expected list, got %T", raw)
		}
		if target.Kind() == reflect.Array && rawValue.Len() != target.Len() {
			return nil, fmt.Errorf("expected exactly %d items for %s, got %d", target.Len(), target, rawValue.Len())
		}
		result := reflect.MakeSlice(reflect.SliceOf(target.Elem()), rawValue.Len(), rawValue.Len())
		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

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Pass a JSON array: --ids '["a","b"]'
Use the repeated-flag encoding if the field declares it: --ids a --ids b
Inspect schema output for the field's declared type to confirm it is a list

Example fix

// before
--members "alice,bob"
// after
--members '["alice","bob"]'

Defensive patterns

Strategy: type-guard

Validate before calling

const v = JSON.parse(raw); if (!Array.isArray(v)) throw new Error('list required for --ids')

Type guard

func isJSONList(s string) (list bool) { var v any; if json.Unmarshal([]byte(s), &v) != nil { return false }; _, ok := v.([]any); return ok }

Try / catch

if strings.HasPrefix(err.Error(), "expected list") { /* wrap the scalar into [value] or switch to the repeated-flag form */ }

Prevention

Check schema for list-typed fields and always pass JSON arrays
Use repeated flags (--ids a --ids b) when the field encoding allows
Never pass bare comma-separated strings to list fields

When it happens

Trigger: Passing a scalar to a list-typed input, e.g. --ids '1,2,3' as a plain string where the field expects a JSON array '["1","2"]', or a single object where a list of objects is required.

Common situations: Confusing comma-separated string flags with array-typed JSON inputs; schema change turned a field into a list; copying an example that omitted the brackets.

Related errors

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