larksuite/cli · error

Args field %s (--%s): %w

Error message

Args field %s (--%s): %w

What it means

This wraps any error returned by mergeInputSupplement when an Input.Fields supplement is merged onto a matching compiled Args field. The wrapper adds context identifying the offending Args field and its flag; the underlying %w cause (from mergeInputSupplement) describes the concrete problem, such as an invalid CLI option or conflicting supplement metadata.

Source

Thrown at shortcuts/common/typed_compile_args.go:55

	}
	var fields []compiledInputField
	seenGo := make(map[string]struct{})
	if err := collectArgFields(argsType, nil, false, &fields, seenGo, supplements); err != nil {
		return nil, nil, err
	}
	fieldByName := make(map[string]int, len(fields))
	allNames := make(map[string]string, len(fields))
	for i := range fields {
		field := &fields[i]
		if previous, exists := allNames[field.name]; exists {
			return nil, nil, fmt.Errorf("Args field %s flag --%s duplicates %s", field.goName, field.name, previous)
		}
		allNames[field.name] = "--" + field.name
		fieldByName[field.name] = i
		supplement, hasSupplement := supplements[field.name]
		if hasSupplement {
			if err := mergeInputSupplement(field, supplement); err != nil {
				return nil, nil, fmt.Errorf("Args field %s (--%s): %w", field.goName, field.name, err)
			}
			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 {

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Read the wrapped cause (%w) after this prefix to find the specific supplement problem.
2. Fix the supplement's CLI/metadata to satisfy mergeInputSupplement validation.
3. Remove the supplement if the struct field's own tags already express the desired metadata.

err := compileDefinition(def)
if err != nil {
  var typed *errs.Typed
  if errors.As(err, &typed) {
    log.Printf("field-level failure: %s (cause: %v)", typed.Message, errors.Unwrap(err))
  }
}

if err := compileDefinition(def); err != nil {
  cause := errors.Unwrap(err)
  return fmt.Errorf("supplement merge failed: %w", cause)
}

When it happens

Trigger: Providing a typedInputField supplement in definition.Fields whose CLI metadata (aliases, defaults, hidden, etc.) fails mergeInputSupplement's validation for the struct field it targets, during compileInput.

Common situations: Supplement declaring an invalid alias format; supplement trying to change immutable field attributes; typo'd supplement values after refactoring the struct field.

Related errors

• Input.Fields[%d].Name %q is not a canonical flag name
• Input.Fields contains duplicate flag %q
• Input.Fields references unknown flag --%s
• Invalid column: {column!r}
• Invalid column index: {index}

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