larksuite/cli · error

name %q must not include leading dashes

Error message

name %q must not include leading dashes

What it means

The flagalias package binds flag alias specs onto a cobra command, and every alias name must be usable as a bare flag token. validateAliasName rejects names starting with '-' because pflag convention treats leading dashes as prefix syntax, not part of the flag name; a dashed alias would be unmatchable or ambiguous when users type it. Bind calls validateAliasName on each Spec's name before registering, so a malformed spec fails fast at command construction.

Source

Thrown at internal/flagalias/flagalias.go:276

	}
	if value, ok := flag.Value.(*trackedSliceValue); ok {
		return value.trackedValue
	}
	tracked := &trackedValue{Value: flag.Value, canonical: flag.Name}
	if slice, ok := flag.Value.(pflag.SliceValue); ok {
		flag.Value = &trackedSliceValue{trackedValue: tracked, slice: slice}
	} else {
		flag.Value = tracked
	}
	return tracked
}

func validateAliasName(name string) error {
	switch {
	case name == "":
		return fmt.Errorf("name must not be empty")
	case strings.HasPrefix(name, "-"):
		return fmt.Errorf("name %q must not include leading dashes", name)
	case strings.ContainsAny(name, " \t\r\n"):
		return fmt.Errorf("name %q must not contain whitespace", name)
	case strings.Contains(name, "="):
		return fmt.Errorf("name %q must not contain '='", name)
	default:
		return nil
	}
}

func collectRegistered(dst map[string]string, set *pflag.FlagSet) {
	if set == nil {
		return
	}
	set.VisitAll(func(flag *pflag.Flag) {
		dst[flag.Name] = flag.Name
	})
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Strip leading dashes from the spec name before building the Spec (strings.TrimLeft(name, "-")).
2. Pass only the bare flag token: use "verbose", not "--verbose"; the dash spelling is what users type on the command line, not what goes in the spec.
3. If the name comes from config or user input, validate/normalize it at config-load time with the same rules (no leading '-', whitespace, or '=').
4. Log or list all specs on failure since Bind validates names one at a time and stops at the first bad one.

Example fix

// before
specs := []flagalias.Spec{{Name: "--json-output", Target: "json"}}
err := flagalias.Bind(cmd, specs)
// after
specs := []flagalias.Spec{{Name: "json-output", Target: "json"}}
err := flagalias.Bind(cmd, specs)

func validAliasName(name string) bool {
	return name != "" && !strings.HasPrefix(name, "-") &&
		!strings.ContainsAny(name, " \t\r\n") && !strings.Contains(name, "=")
}
// before Bind:
for _, s := range specs {
	if !validAliasName(s.Name) {
		return fmt.Errorf("invalid alias spec name %q", s.Name)
	}
}

func isRegistrableName(name string) bool {
	return name != "" && !strings.HasPrefix(name, "-") &&
		!strings.ContainsAny(name, " \t\r\n") && !strings.Contains(name, "=")
}

When it happens

Trigger: Calling flagalias.Bind(cmd, specs) where any Spec.Name (or alias entry validated through validateAliasName) begins with one or more '-' characters, e.g. Name: "--verbose" or Name: "-v" instead of "verbose" or "v".

Common situations: Copy-pasting a full CLI invocation like "--output json" into a spec literal; building spec names dynamically from user/flag strings that already carry dashes; converting old shell wrapper scripts where flags were written with dashes.

Related errors

• name %q must not contain whitespace
• name %q must not contain '='
• name must not be empty
• Multiple sheets matched; pass --sheet-id or --sheet-name
• invalid --param format

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