larksuite/cli · error

%s input must explicitly declare CLI encoding

Error message

%s input must explicitly declare CLI encoding

What it means

Complex value types (slice, array, struct, map, interface) cannot be converted from a single CLI string without an explicit encoding rule. validateInputCLI requires such fields to declare field.cli.Encoding explicitly; an empty encoding on a complex kind is rejected with the kind named in the message.

Source

Thrown at shortcuts/common/typed_compile_args.go:302

			return fmt.Errorf("unknown value source %q", source)
		}
		if _, duplicate := seenSources[source]; duplicate {
			return fmt.Errorf("duplicate value source %q", source)
		}
		seenSources[source] = struct{}{}
	}
	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:

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Declare the encoding explicitly: "json" for JSON bodies, "repeated" for string arrays, or "comma_or_repeated" for string/integer arrays
2. Change a simple []string field to encoding repeated instead of json if each element is a separate flag occurrence
3. If the field is actually scalar, simplify the value type so no encoding is needed

Example fix

// before
cli:"--items" // []string field with no encoding
// after
cli:"--items,encoding=repeated"

func needsEncoding(t reflect.Type) bool {
	k := t
	for k.Kind() == reflect.Ptr {
		k = k.Elem()
	}
	switch k.Kind() {
	case reflect.Slice, reflect.Array, reflect.Struct, reflect.Map, reflect.Interface:
		return true
	}
	return false
}
// if needsEncoding(t) { require cli.Encoding != "" }

if err := compileInput(...); err != nil {
	if strings.Contains(err.Error(), "must explicitly declare CLI encoding") {
		// add encoding=json / repeated / comma_or_repeated to the tag
	}
	return err
}

When it happens

Trigger: Declaring an input field whose indirect kind is slice/array/struct/map/interface via the cli tag or InputField.CLI while leaving Encoding empty. Raised by compileInput during shortcut compilation.

Common situations: Adding a []string or struct input to a shortcut and forgetting to say how CLI text maps to it; relying on a default encoding that no longer exists after a library change; auto-generating fields where the encoding field was skipped.

Related errors

• complex input requires 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/039796d5070cd3df. Report an issue: GitHub.