{"record":{"id":"57c982e70ab688fb","repo":"larksuite/cli","slug":"input-fields-references-unknown-flag-s","errorCode":null,"errorMessage":"Input.Fields references unknown flag --%s","messagePattern":"Input\\.Fields references unknown flag --(.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"shortcuts/common/typed_compile_args.go","lineNumber":74,"sourceCode":"\t\t\t}\n\t\t\tdelete(supplements, field.name)\n\t\t}\n\t\tif field.description == \"\" {\n\t\t\treturn nil, nil, fmt.Errorf(\"Args field %s (--%s): description is required via doc or InputField.Description\", field.goName, field.name)\n\t\t}\n\t\tif err := validateInputCLI(field); err != nil {\n\t\t\treturn nil, nil, fmt.Errorf(\"Args field %s (--%s): %w\", field.goName, field.name, err)\n\t\t}\n\t\tfor _, alias := range field.cli.Aliases {\n\t\t\tif previous, exists := allNames[alias.Name]; exists {\n\t\t\t\treturn nil, nil, fmt.Errorf(\"Args field %s (--%s): alias --%s duplicates %s\", field.goName, field.name, alias.Name, previous)\n\t\t\t}\n\t\t\tallNames[alias.Name] = \"alias of --\" + field.name\n\t\t}\n\t}\n\tif len(supplements) > 0 {\n\t\tfor name := range supplements {\n\t\t\treturn nil, nil, fmt.Errorf(\"Input.Fields references unknown flag --%s\", name)\n\t\t}\n\t}\n\treturn fields, fieldByName, nil\n}\n\nfunc collectArgFields(t reflect.Type, parentIndex []int, insideInline bool, out *[]compiledInputField, seenGo map[string]struct{}, supplements map[string]typedInputField) error {\n\tfor i := 0; i < t.NumField(); i++ {\n\t\tfield := t.Field(i)\n\t\tif !field.IsExported() {\n\t\t\tif hasAnyTag(field, \"flag\", \"arg\", \"schema\", \"cli\", \"doc\", \"json\") {\n\t\t\t\treturn fmt.Errorf(\"Args field %s is unexported but declares Typed input tags\", field.Name)\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\t\tflagName, hasFlag := field.Tag.Lookup(\"flag\")\n\t\targMode, hasArg := field.Tag.Lookup(\"arg\")\n\t\tif hasFlag == hasArg {\n\t\t\treturn fmt.Errorf(\"Args field %s must declare exactly one of flag or arg\", field.Name)","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/shortcuts/common/typed_compile_args.go#L56-L92","documentation":"After merging supplements onto compiled fields, compileInput checks that every Input.Fields entry actually matched a struct field flag. Leftover entries in the supplements map mean the supplement referenced a flag name that no Args field produces, so the definition is rejected to avoid silently ignored supplement metadata.","triggerScenarios":"Adding an InputField whose Name does not match any compiled flag (typo, renamed struct field, flag on a non-inlined nested struct) and compiling the definition.","commonSituations":"Renaming a struct field's flag tag without updating Input.Fields; adding supplements for flags on optional/nested structs that aren't reached; typos in supplement names.","solutions":["Fix the supplement Name to exactly match an existing struct field's flag name.","Remove the stale Input.Fields entry if the flag no longer exists.","Search the Args struct for the intended field and update the flag tag or the supplement consistently."],"exampleFix":"// before\nFields: []typedInputField{{Name: \"usr-id\", Description: \"user id\"}}\n// after\nFields: []typedInputField{{Name: \"user-id\", Description: \"user id\"}}","handlingStrategy":"validation","validationCode":"func supplementsMatchFlags(def typedInputDefinition, flagNames []string) error {\n  known := map[string]bool{}\n  for _, n := range flagNames { known[n] = true }\n  for _, f := range def.Fields {\n    if !known[f.Name] { return fmt.Errorf(\"supplement references unknown flag --%s\", f.Name) }\n  }\n  return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Update Input.Fields whenever a field's flag tag is renamed.","Generate supplements from the struct's flag names, not by hand.","Compile all definitions in CI to catch stale references."],"tags":["go","flags","validation","typed-input"],"backgroundTag":"unknown-flag-reference","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"}