larksuite/cli · error

complex input requires encoding

Error message

complex input requires encoding

What it means

This is the switch-based counterpart to the explicit-declaration check: if field.cli.Encoding is empty and the indirect kind is a complex kind (slice, array, struct, map, interface), the field cannot be compiled. In practice the earlier check (line 301) rejects this first for complex kinds, so this branch guards the encoding switch invariant.

Source

Thrown at shortcuts/common/typed_compile_args.go:308

	}
	if len(field.cli.ValueSources) > 0 {
		if _, ok := seenSources[typedSourceFlag]; !ok {
			return fmt.Errorf("ValueSources must include flag")
		}
		if (len(seenSources) > 1) && indirectKind(field.valueType) != reflect.String && field.cli.Encoding != typedEncodingJSON {
			return fmt.Errorf("file/stdin sources require string input or encoding=json")
		}
	}
	kind := indirectKind(field.valueType)
	if kind == reflect.Slice || kind == reflect.Array || kind == reflect.Struct || kind == reflect.Map || kind == reflect.Interface {
		if field.cli.Encoding == "" {
			return fmt.Errorf("%s input must explicitly declare CLI encoding", kind)
		}
	}
	switch field.cli.Encoding {
	case "":
		if kind == reflect.Slice || kind == reflect.Array || kind == reflect.Struct || kind == reflect.Map || kind == reflect.Interface {
			return fmt.Errorf("complex input requires encoding")
		}
	case typedEncodingRepeated:
		if kind != reflect.Slice && kind != reflect.Array {
			return fmt.Errorf("encoding repeated requires an array or slice")
		}
		if indirectType(field.valueType).Elem().Kind() != reflect.String {
			return fmt.Errorf("encoding repeated only supports string arrays")
		}
		if field.nullable != nil {
			return fmt.Errorf("encoding repeated does not allow nullable/nonnullable")
		}
	case typedEncodingCommaOrRepeated:
		if kind != reflect.Slice && kind != reflect.Array {
			return fmt.Errorf("encoding comma_or_repeated requires an array or slice")
		}
		elementKind := indirectType(field.valueType).Elem().Kind()
		if elementKind != reflect.String && !isIntegerKind(elementKind) {
			return fmt.Errorf("encoding comma_or_repeated only supports string or integer arrays")

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Set an explicit encoding (json, repeated, or comma_or_repeated) matching the field's type
2. Make the field type scalar (string/int/bool) so encoding is unnecessary
3. Verify the cli tag string actually includes the encoding segment (spelling: encoding=json)

Example fix

// before
CLI{Flag: "payload"} // struct field, Encoding ""
// after
CLI{Flag: "payload", Encoding: "json"}

// same guard as 625: complex kinds must not reach the encoding switch with Encoding == ""
if needsEncoding(fieldType) && cli.Encoding == "" {
	return errors.New("set encoding before compiling")
}

if err := compileInput(...); err != nil {
	if strings.Contains(err.Error(), "complex input requires encoding") {
		// assign an explicit encoding and recompile
	}
	return err
}

When it happens

Trigger: An input field with a complex indirect kind and empty cli.Encoding reaching the encoding switch - i.e. a complex input with no encoding declared. Raised by compileInput during shortcut compilation.

Common situations: Same root cause as 'must explicitly declare CLI encoding': forgetting encoding=json/repeated/comma_or_repeated on a slice/struct/map/interface field; constructing InputField structs programmatically and leaving Encoding zero-valued.

Related errors

• %s input must explicitly declare CLI encoding
• file/stdin sources require string input or encoding=json
• encoding repeated requires an array or slice
• encoding repeated only supports string arrays
• encoding repeated does not allow nullable/nonnullable

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