larksuite/cli · error

Args field %s must declare exactly one of flag or arg

Error message

Args field %s must declare exactly one of flag or arg

What it means

collectArgFields compile-time contract: an exported Args struct field carries both `flag` and `arg` tags (or neither) - hasFlag == hasArg - so the reflection compiler cannot decide the input kind. Fires during compileInput, not at runtime from user input.

Source

Thrown at shortcuts/common/typed_compile_args.go:92

			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)
		}
		if _, duplicate := seenGo[field.Name]; duplicate {
			return fmt.Errorf("Args field %s is duplicated through inline expansion", field.Name)
		}
		seenGo[field.Name] = struct{}{}
		index := append(append([]int(nil), parentIndex...), i)
		if hasArg {
			switch argMode {
			case "local":
				if insideInline {
					return fmt.Errorf("Args field %s: arg:\"local\" is not allowed inside inline", field.Name)
				}
				if hasAnyTag(field, "flag", "schema", "cli", "doc", "json") {
					return fmt.Errorf("Args field %s: arg:\"local\" cannot declare public input tags", field.Name)
				}
			case "inline":
				if insideInline {
					return fmt.Errorf("Args field %s: nested arg:\"inline\" is not allowed", field.Name)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Give the field exactly one of the `flag` or `arg` struct tags

When it happens

Trigger: Thrown at shortcuts/common/typed_compile_args.go:92 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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