{"record":{"id":"837379a4a70ebd20","repo":"larksuite/cli","slug":"encoding-json-requires-array-object-oneof-or-cu","errorCode":null,"errorMessage":"encoding json requires array, object, oneOf, or custom JSON input","messagePattern":"encoding json requires array, object, oneOf, or custom JSON input","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"shortcuts/common/typed_compile_args.go","lineNumber":333,"sourceCode":"\t\t\treturn fmt.Errorf(\"encoding repeated only supports string arrays\")\n\t\t}\n\t\tif field.nullable != nil {\n\t\t\treturn fmt.Errorf(\"encoding repeated does not allow nullable/nonnullable\")\n\t\t}\n\tcase typedEncodingCommaOrRepeated:\n\t\tif kind != reflect.Slice && kind != reflect.Array {\n\t\t\treturn fmt.Errorf(\"encoding comma_or_repeated requires an array or slice\")\n\t\t}\n\t\telementKind := indirectType(field.valueType).Elem().Kind()\n\t\tif elementKind != reflect.String && !isIntegerKind(elementKind) {\n\t\t\treturn fmt.Errorf(\"encoding comma_or_repeated only supports string or integer arrays\")\n\t\t}\n\t\tif field.nullable != nil {\n\t\t\treturn fmt.Errorf(\"encoding comma_or_repeated does not allow nullable/nonnullable\")\n\t\t}\n\tcase typedEncodingJSON:\n\t\tif kind != reflect.Slice && kind != reflect.Array && kind != reflect.Struct && kind != reflect.Map && kind != reflect.Interface {\n\t\t\treturn fmt.Errorf(\"encoding json requires array, object, oneOf, or custom JSON input\")\n\t\t}\n\t\tif isNilCapable(field.valueType) && field.nullable == nil && !field.shapeExplicit && !shapeExplicitlyNullable(field.shape) {\n\t\t\treturn fmt.Errorf(\"nil-capable encoding=json input must declare nullable or nonnullable\")\n\t\t}\n\tdefault:\n\t\treturn fmt.Errorf(\"unknown CLI encoding %q\", field.cli.Encoding)\n\t}\n\tseenAliases := make(map[string]struct{})\n\tfor i, alias := range field.cli.Aliases {\n\t\tif !aliasNamePattern.MatchString(alias.Name) {\n\t\t\treturn fmt.Errorf(\"alias[%d] name %q is invalid\", i, alias.Name)\n\t\t}\n\t\tif alias.Name == field.name {\n\t\t\treturn fmt.Errorf(\"alias[%d] duplicates canonical flag --%s\", i, field.name)\n\t\t}\n\t\tif _, duplicate := seenAliases[alias.Name]; duplicate {\n\t\t\treturn fmt.Errorf(\"duplicate alias --%s\", alias.Name)\n\t\t}","sourceCodeStart":315,"sourceCodeEnd":351,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/shortcuts/common/typed_compile_args.go#L315-L351","documentation":"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.","triggerScenarios":"A field of type string, int, bool, etc. declares cli:\"encoding=json\"; validateInputCLI's kind check (Slice/Array/Struct/Map/Interface) fails during compileInput.","commonSituations":"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.","solutions":["Remove the encoding=json declaration; scalar fields are parsed directly from the flag value.","If JSON input is intended, change the field type to a struct, map, slice, or interface.","For a string that happens to contain JSON, keep it a plain string without encoding."],"exampleFix":"// before\nPayload string `schema:\"optional\" cli:\"encoding=json\"`\n// after\nPayload map[string]any `schema:\"optional\" cli:\"encoding=json\"`","handlingStrategy":"validation","validationCode":"func validJSONEncoding(t reflect.Type) error {\n\tswitch t.Kind() {\n\tcase reflect.Slice, reflect.Array, reflect.Struct, reflect.Map, reflect.Interface:\n\t\treturn nil\n\t}\n\treturn fmt.Errorf(\"encoding=json requires complex type, got %v\", t.Kind())\n}","typeGuard":"func acceptsJSONEncoding(t reflect.Type) bool {\n\tswitch t.Kind() {\n\tcase reflect.Slice, reflect.Array, reflect.Struct, reflect.Map, reflect.Interface:\n\t\treturn true\n\t}\n\treturn false\n}","tryCatchPattern":null,"preventionTips":["Only put encoding=json on struct/map/slice/interface fields.","Remember encoding is about CLI list syntax, not JSON parsing of scalars.","Compile all input structs in CI to catch tag/type mismatches early."],"tags":["cli","schema","type-mismatch","authoring-time"],"backgroundTag":"invalid-cli-tag-encoding","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}