larksuite/cli · error

encoding json requires array, object, oneOf, or custom JSON

Error message

encoding json requires array, object, oneOf, or custom JSON input

What it means

encoding=json is reserved for fields holding complex values: slices, arrays, structs, maps, or interfaces (rendered as array/object/oneOf/custom JSON input). Declaring encoding=json on a scalar field is rejected because the CLI would have nowhere meaningful to put a JSON document.

Source

Thrown at shortcuts/common/typed_compile_args.go:333

			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")
		}
		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)
		}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Remove the encoding=json declaration; scalar fields are parsed directly from the flag value.
2. If JSON input is intended, change the field type to a struct, map, slice, or interface.
3. For a string that happens to contain JSON, keep it a plain string without encoding.

Example fix

// before
Payload string `schema:"optional" cli:"encoding=json"`
// after
Payload map[string]any `schema:"optional" cli:"encoding=json"`

func validJSONEncoding(t reflect.Type) error {
	switch t.Kind() {
	case reflect.Slice, reflect.Array, reflect.Struct, reflect.Map, reflect.Interface:
		return nil
	}
	return fmt.Errorf("encoding=json requires complex type, got %v", t.Kind())
}

func acceptsJSONEncoding(t reflect.Type) bool {
	switch t.Kind() {
	case reflect.Slice, reflect.Array, reflect.Struct, reflect.Map, reflect.Interface:
		return true
	}
	return false
}

When it happens

Trigger: A field of type string, int, bool, etc. declares cli:"encoding=json"; validateInputCLI's kind check (Slice/Array/Struct/Map/Interface) fails during compileInput.

Common situations: Thinking encoding=json makes the CLI parse the value as JSON (it does not apply to scalars); copying a json encoding from an object-typed input onto a scalar helper field.

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
• nil-capable encoding=json input must declare nullable or non
• unknown CLI encoding %q

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