larksuite/cli · error

%s declares aliases for unregistered flag --%s

Error message

%s declares aliases for unregistered flag --%s

What it means

Validation in Bind: a spec declares aliases for a canonical flag name that is not registered on the command (after normalization). The alias target must be an existing pflag; this catches typos or aliases declared before flag registration.

Source

Thrown at internal/flagalias/flagalias.go:83

	collectRegistered(registered, cmd.InheritedFlags())

	// Existing annotations matter when Bind is composed by multiple adapters:
	// aliases are not independent pflags, so VisitAll alone cannot see them.
	acceptedAliases := make(map[string]string)
	collectAnnotatedAliases(acceptedAliases, flagSet, normalize)
	collectAnnotatedAliases(acceptedAliases, cmd.InheritedFlags(), normalize)

	aliases := make(map[string]string)
	metadata := make(map[*pflag.Flag][]string)
	canonicalFlags := make(map[string]*pflag.Flag)
	seenCanonical := make(map[string]struct{})
	for _, spec := range specs {
		if len(spec.Aliases) == 0 {
			continue
		}
		canonicalFlag := flagSet.Lookup(spec.Canonical)
		if canonicalFlag == nil {
			return fmt.Errorf("%s declares aliases for unregistered flag --%s", cmd.CommandPath(), spec.Canonical)
		}
		canonical := canonicalFlag.Name
		if _, exists := seenCanonical[canonical]; exists {
			return fmt.Errorf("%s declares flag aliases for --%s more than once after normalization", cmd.CommandPath(), canonical)
		}
		seenCanonical[canonical] = struct{}{}
		canonicalFlags[canonical] = canonicalFlag
		for _, alias := range spec.Aliases {
			if err := validateAliasName(alias); err != nil {
				return fmt.Errorf("%s alias for --%s: %w", cmd.CommandPath(), canonical, err)
			}
			normalized := normalize(alias)
			if normalized == "" {
				return fmt.Errorf("%s alias --%s for --%s normalizes to an empty name", cmd.CommandPath(), alias, canonical)
			}
			if normalized == canonical {
				return fmt.Errorf("%s declares --%s as an alias of itself (--%s after normalization)", cmd.CommandPath(), alias, canonical)
			}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Register the canonical flag before binding aliases for it
2. Fix the canonical name spelling in the alias Spec

When it happens

Trigger: Thrown at internal/flagalias/flagalias.go:83 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/0395fdadda861070. Report an issue: GitHub.