What causes "Input.Fields references unknown flag --%s" in larksuite/cli?

Fix the supplement Name to exactly match an existing struct field's flag name.

Input.Fields references unknown flag --%s

Error message

Input.Fields references unknown flag --%s

What it means

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.

Source

Thrown at shortcuts/common/typed_compile_args.go:74

			}
			delete(supplements, field.name)
		}
		if field.description == "" {
			return nil, nil, fmt.Errorf("Args field %s (--%s): description is required via doc or InputField.Description", field.goName, field.name)
		}
		if err := validateInputCLI(field); err != nil {
			return nil, nil, fmt.Errorf("Args field %s (--%s): %w", field.goName, field.name, err)
		}
		for _, alias := range field.cli.Aliases {
			if previous, exists := allNames[alias.Name]; exists {
				return nil, nil, fmt.Errorf("Args field %s (--%s): alias --%s duplicates %s", field.goName, field.name, alias.Name, previous)
			}
			allNames[alias.Name] = "alias of --" + field.name
		}
	}
	if len(supplements) > 0 {
		for name := range supplements {
			return nil, nil, fmt.Errorf("Input.Fields references unknown flag --%s", name)
		}
	}
	return fields, fieldByName, nil
}

func collectArgFields(t reflect.Type, parentIndex []int, insideInline bool, out *[]compiledInputField, seenGo map[string]struct{}, supplements map[string]typedInputField) error {
	for i := 0; i < t.NumField(); i++ {
		field := t.Field(i)
		if !field.IsExported() {
			if hasAnyTag(field, "flag", "arg", "schema", "cli", "doc", "json") {
				return fmt.Errorf("Args field %s is unexported but declares Typed input tags", field.Name)
			}
			continue
		}
		flagName, hasFlag := field.Tag.Lookup("flag")
		argMode, hasArg := field.Tag.Lookup("arg")
		if hasFlag == hasArg {
			return fmt.Errorf("Args field %s must declare exactly one of flag or arg", field.Name)

View on GitHub (pinned to 7fd6ef3c07)

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.

Example fix

// before
Fields: []typedInputField{{Name: "usr-id", Description: "user id"}}
// after
Fields: []typedInputField{{Name: "user-id", Description: "user id"}}

Defensive patterns

Strategy: validation

Validate before calling

func supplementsMatchFlags(def typedInputDefinition, flagNames []string) error {
  known := map[string]bool{}
  for _, n := range flagNames { known[n] = true }
  for _, f := range def.Fields {
    if !known[f.Name] { return fmt.Errorf("supplement references unknown flag --%s", f.Name) }
  }
  return nil
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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