larksuite/cli · error

Input.Fields[%d].Name %q is not a canonical flag name

Error message

Input.Fields[%d].Name %q is not a canonical flag name

What it means

compileInput validates every supplemental Input.Fields entry name against flagNamePattern before merging it into compiled fields. Names must be canonical kebab-case flags (e.g. lower-case words separated by hyphens); anything else (underscores, CamelCase, leading dashes, spaces) is rejected with this error so help output and CLI parsing stay canonical.

Source

Thrown at shortcuts/common/typed_compile_args.go:31

	"strconv"
	"strings"
)

var (
	flagNamePattern  = regexp.MustCompile(`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
	aliasNamePattern = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]*$`)
)

const extensionCommandPkgPath = "github.com/larksuite/cli/extension/command"

func compileInput(argsType reflect.Type, definition typedInputDefinition) ([]compiledInputField, map[string]int, error) {
	if argsType.Kind() != reflect.Struct {
		return nil, nil, fmt.Errorf("Args must be a non-pointer struct, got %s", argsType)
	}
	supplements := make(map[string]typedInputField, len(definition.Fields))
	for i, supplement := range definition.Fields {
		if !flagNamePattern.MatchString(supplement.Name) {
			return nil, nil, fmt.Errorf("Input.Fields[%d].Name %q is not a canonical flag name", i, supplement.Name)
		}
		if _, exists := supplements[supplement.Name]; exists {
			return nil, nil, fmt.Errorf("Input.Fields contains duplicate flag %q", supplement.Name)
		}
		supplements[supplement.Name] = supplement
	}
	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)
		}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Rename the field to canonical kebab-case, e.g. "task-id".
2. Remove the '--' prefix — the framework adds dashes itself.
3. Verify against flagNamePattern (lowercase letters/digits, hyphen-separated) before compiling.

Example fix

// before
{Name: "task_id", Description: "task id"}
// after
{Name: "task-id", Description: "task id"}

var flagNameRe = regexp.MustCompile(`^[a-z][a-z0-9]*(-[a-z0-9]+)*$`)
func validFlagNames(fields []typedInputField) error {
  for _, f := range fields {
    if !flagNameRe.MatchString(f.Name) {
      return fmt.Errorf("flag %q is not canonical kebab-case", f.Name)
    }
  }
  return nil
}

When it happens

Trigger: Adding a typedInputField to definition.Fields whose Name is e.g. "task_id", "taskId", "--task-id", or "Task ID" and compiling the definition.

Common situations: Reusing a JSON/Go field name as the flag name; hand-writing flag names with underscores from another convention; accidentally prefixing the name with '--' since the pattern expects the bare name.

Related errors

• %s: %q is not a valid skill name
• Input.Fields contains duplicate flag %q
• Args field %s (--%s): %w
• Input.Fields references unknown flag --%s
• Invalid column: {column!r}

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