%s alias --%s for --%s conflicts with registered flag --%s a

Error message

%s alias --%s for --%s conflicts with registered flag --%s after normalization

What it means

Bind rejects an alias declaration when, after applying the configured normalizer, the alias name is already registered as a real (canonical) flag on the command. This guard keeps the one-alias-to-one-canonical-flag mapping unambiguous: an alias that normalizes onto an existing flag could otherwise silently override or shadow that flag. Bind returns this error during registration, before any parsing happens.

Source

Thrown at internal/flagalias/flagalias.go:103

		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)
			}
			if existing, ok := registered[normalized]; ok {
				return fmt.Errorf("%s alias --%s for --%s conflicts with registered flag --%s after normalization", cmd.CommandPath(), alias, canonical, existing)
			}
			if existing, ok := acceptedAliases[normalized]; ok {
				return fmt.Errorf("%s alias --%s for --%s conflicts with existing alias for --%s after normalization to --%s", cmd.CommandPath(), alias, canonical, existing, normalized)
			}
			if existing, ok := aliases[normalized]; ok {
				if existing == canonical {
					return fmt.Errorf("%s declares duplicate alias --%s for --%s after normalization to --%s", cmd.CommandPath(), alias, canonical, normalized)
				}
				return fmt.Errorf("%s alias --%s maps to both --%s and --%s after normalization to --%s", cmd.CommandPath(), alias, existing, canonical, normalized)
			}
			aliases[normalized] = canonical
			metadata[canonicalFlag] = append(metadata[canonicalFlag], alias)
		}
	}

	if len(aliases) == 0 {
		return nil
	}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Remove or rename the alias so its normalized form no longer collides with the registered flag name
Register the colliding name as the canonical flag instead of an alias, and drop the duplicate native flag
Change the normalizer so alias and flag names no longer converge to the same value
Split the flags across different commands/subcommands if both names are genuinely needed

Example fix

// before
Bind(cmd, Alias("verbose", "Verbose")) // with lowercasing normalizer and existing --verbose flag
// after
Bind(cmd, Alias("v", "Verbose"))

Defensive patterns

Strategy: validation

Validate before calling

func checkAliasConflict(cmd *cobra.Command, aliases []flagalias.Alias, norm func(string) string) error {
	registered := map[string]bool{}
	for _, f := range cmd.Flags() { registered[f.Name] = true }
	seen := map[string]string{}
	for _, a := range aliases {
		n := norm(a.Alias)
		if registered[n] && n != norm(a.Canonical) {
			return fmt.Errorf("alias %q conflicts with registered flag --%s", n, n)
		}
		seen[n] = a.Canonical
	}
	return nil
}

Try / catch

if err := flagalias.MustBind(cmd, aliases...); err != nil {
	var conflict *flagalias.ConflictError
	if errors.As(err, &conflict) { log.Fatalf("fix alias table: %v", err) }
	return err
}

Prevention

Run the same normalization on aliases and canonical names and diff against cmd.Flags() in a unit test
Keep alias tables in one place and deduplicate before Bind
Add a startup-time Bind call in tests so conflicts fail CI, not runtime

When it happens

Trigger: Calling cmd, Bind(...) (directly or via MustBind) where an alias declared for canonical flag X, after normalization (e.g. lowercasing, underscore stripping), equals the name of a different flag already registered on the same Cobra command, so registered[normalized] matches a name other than the canonical target.

Common situations: Configuring aliases like --log-level for --logLevel with a normalizer that lowercases names while a native --log-level flag already exists; renaming a canonical flag in a new version while keeping the old name as an alias; two teams independently registering flags on a shared command.

Related errors

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