larksuite/cli · error

unknown CLI encoding %q

Error message

unknown CLI encoding %q

What it means

Validation in validateInputCLI: the encoding name in the cli tag is not a known typed encoding. Only the registered typedEncoding values (e.g. comma_or_repeated, json) are accepted.

Source

Thrown at shortcuts/common/typed_compile_args.go:339

		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")
		}
		if field.nullable != nil {
			return fmt.Errorf("encoding comma_or_repeated does not allow nullable/nonnullable")
		}
	case typedEncodingJSON:
		if kind != reflect.Slice && kind != reflect.Array && kind != reflect.Struct && kind != reflect.Map && kind != reflect.Interface {
			return fmt.Errorf("encoding json requires array, object, oneOf, or custom JSON input")
		}
		if isNilCapable(field.valueType) && field.nullable == nil && !field.shapeExplicit && !shapeExplicitlyNullable(field.shape) {
			return fmt.Errorf("nil-capable encoding=json input must declare nullable or nonnullable")
		}
	default:
		return fmt.Errorf("unknown CLI encoding %q", field.cli.Encoding)
	}
	seenAliases := make(map[string]struct{})
	for i, alias := range field.cli.Aliases {
		if !aliasNamePattern.MatchString(alias.Name) {
			return fmt.Errorf("alias[%d] name %q is invalid", i, alias.Name)
		}
		if alias.Name == field.name {
			return fmt.Errorf("alias[%d] duplicates canonical flag --%s", i, field.name)
		}
		if _, duplicate := seenAliases[alias.Name]; duplicate {
			return fmt.Errorf("duplicate alias --%s", alias.Name)
		}
		seenAliases[alias.Name] = struct{}{}
		switch alias.Mode {
		case typedAliasNormalize:
			if alias.Conflict != "" {
				return fmt.Errorf("normalize alias --%s cannot declare Conflict", alias.Name)
			}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Correct the encoding name to one of: repeated, comma_or_repeated, json.
2. Remove the encoding for scalar fields that need none.
3. Search the codebase for typedEncoding* constants to see the exact supported set and spelling.

Example fix

// before
IDs []int64 `schema:"optional" cli:"encoding=repeated-list"`
// after
IDs []int64 `schema:"optional" cli:"encoding=comma_or_repeated"`

var validEncodings = map[string]bool{"repeated": true, "comma_or_repeated": true, "json": true}
func encodingKnown(tagVal string) error {
	// tagVal like "encoding=csv"
	for _, part := range strings.Split(tagVal, ";") {
		if enc, ok := strings.CutPrefix(part, "encoding="); ok && !validEncodings[enc] {
			return fmt.Errorf("unknown encoding %q", enc)
		}
	}
	return nil
}

When it happens

Trigger: A field declares cli:"encoding=csv", "encoding=list", or any misspelled/unknown encoding name (e.g. wrong casing); validateInputCLI reaches `default:` during compileInput.

Common situations: Typos in tag strings (tags are not compile-checked); inventing an encoding that the framework does not implement; casing mistakes like encoding=JSON.

Related errors

• encoding comma_or_repeated requires an array or slice
• encoding comma_or_repeated only supports string or integer a
• encoding comma_or_repeated does not allow nullable/nonnullab
• encoding json requires array, object, oneOf, or custom JSON
• nil-capable encoding=json input must declare nullable or non

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