{"record":{"id":"c278c95d7f545dd6","repo":"larksuite/cli","slug":"s-must-be-an-array","errorCode":null,"errorMessage":"%s must be an array","messagePattern":"(.+?) must be an array","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"shortcuts/common/typed_binder.go","lineNumber":471,"sourceCode":"\tcase typedNumberShape:\n\t\tnumber, ok := validationNumber(value)\n\t\tif !ok {\n\t\t\treturn fmt.Errorf(\"%s must be a number\", path)\n\t\t}\n\t\tif len(constraint.Enum) > 0 && !slices.Contains(constraint.Enum, number) {\n\t\t\treturn fmt.Errorf(\"%s has an unsupported number value\", path)\n\t\t}\n\t\tif constraint.Minimum != nil && number < *constraint.Minimum {\n\t\t\treturn fmt.Errorf(\"%s must be at least %v\", path, *constraint.Minimum)\n\t\t}\n\t\tif constraint.Maximum != nil && number > *constraint.Maximum {\n\t\t\treturn fmt.Errorf(\"%s must be at most %v\", path, *constraint.Maximum)\n\t\t}\n\t\treturn nil\n\tcase typedArrayShape:\n\t\titems, ok := value.([]any)\n\t\tif !ok {\n\t\t\treturn fmt.Errorf(\"%s must be an array\", path)\n\t\t}\n\t\tif constraint.MinItems != nil && len(items) < *constraint.MinItems {\n\t\t\treturn fmt.Errorf(\"%s must contain at least %d items\", path, *constraint.MinItems)\n\t\t}\n\t\tif constraint.MaxItems != nil && len(items) > *constraint.MaxItems {\n\t\t\treturn fmt.Errorf(\"%s must contain at most %d items\", path, *constraint.MaxItems)\n\t\t}\n\t\tfor i, item := range items {\n\t\t\tif err := validateJSONValueAgainstShape(item, constraint.Items, fmt.Sprintf(\"%s[%d]\", path, i)); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t}\n\t\treturn nil\n\tcase typedObjectShape:\n\t\tobject, ok := value.(map[string]any)\n\t\tif !ok {\n\t\t\treturn fmt.Errorf(\"%s must be an object\", path)\n\t\t}","sourceCodeStart":453,"sourceCodeEnd":489,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/shortcuts/common/typed_binder.go#L453-L489","documentation":"Array shape validation: a field declared as a typed array received something that is not a JSON array after decoding. The binder's type assertion to []any fails and it reports the field path with this message.","triggerScenarios":"Passing a scalar, object, or comma-separated string where a JSON array flag is expected — e.g. --member-ids u123 (bare string) instead of '[\"u123\"]'.","commonSituations":"Users unfamiliar with JSON-typed flags passing bare values or space-separated lists; shell quoting stripping brackets so the payload becomes malformed; YAML/config files supplying a string for a list field.","solutions":["Wrap the value as a JSON array: '[\"a\",\"b\"]' with proper shell quoting.","Check --help or schema to confirm the field is an array and its item shape.","Quote the argument so the shell does not eat the brackets.","If building the value programmatically, marshal a slice/JSON array, not a single value."],"exampleFix":"// before\nlark-cli shortcut demo --member-ids ou_x,ou_y\n// error: member_ids must be an array\n\n// after\nlark-cli shortcut demo --member-ids '[\"ou_x\",\"ou_y\"]'","handlingStrategy":"type-guard","validationCode":"value='$1'\nif ! echo \"$value\" | jq -e 'type==\"array\"' >/dev/null; then\n  echo \"expected a JSON array\" >&2; exit 2\nfi","typeGuard":"func isJSONArray(raw string) bool {\n    var v []any\n    return json.Unmarshal([]byte(raw), &v) == nil\n}","tryCatchPattern":"err := cmd.Run()\nvar valErr *errs.ValidationError\nif errors.As(err, &valErr) && strings.Contains(valErr.Error(), \"must be an array\") {\n    // wrap the input in a JSON array and retry\n}","preventionTips":["Always quote JSON arguments single-quoted to protect brackets.","Validate flag payloads with jq before invoking the CLI.","Check the field's item shape in schema output.","Marshal real slices when building flags programmatically."],"tags":["validation","cli","json","type-mismatch"],"backgroundTag":"schema-validation-failed","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"}