%s alias --%s for --%s conflicts with existing alias for --%

Error message

%s alias --%s for --%s conflicts with existing alias for --%s after normalization to --%s

What it means

Bind rejects a declaration when the normalized alias name has already been accepted as an alias for a different canonical flag. Each normalized alias may map to exactly one canonical flag; a second mapping would make flag resolution nondeterministic. The error reports both the previously bound canonical flag and the normalized name so the conflicting declaration can be located.

Source

Thrown at internal/flagalias/flagalias.go:106

		}
		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
	}
	tracked := make(map[string]*trackedValue, len(canonicalFlags))
	for canonical, flag := range canonicalFlags {
		tracked[canonical] = ensureTrackedValue(flag)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Rename one of the aliases so normalized names stay distinct
Map both aliases to the same canonical flag if that was the intent, removing the duplicate declaration
Tighten the normalizer (or disable it) so the two names do not collide
Audit the alias list before Bind with the same normalization to detect collisions early

Example fix

// before
Bind(cmd, Alias("logLevel", "LogLevel"), Alias("log_level", "LogFields"))
// after
Bind(cmd, Alias("logLevel", "LogLevel"), Alias("logFields", "LogFields"))

Defensive patterns

Strategy: validation

Validate before calling

func ensureUniqueAliases(aliases []flagalias.Alias, norm func(string) string) error {
	seen := map[string]string{}
	for _, a := range aliases {
		n := norm(a.Alias)
		if owner, ok := seen[n]; ok && owner != a.Canonical {
			return fmt.Errorf("alias %q maps to both %s and %s", n, owner, a.Canonical)
		}
		seen[n] = a.Canonical
	}
	return nil
}

Try / catch

if err := flagalias.MustBind(cmd, aliases...); err != nil {
	if strings.Contains(err.Error(), "conflicts with existing alias") {
		return fmt.Errorf("alias table ambiguous, dedupe entries: %w", err)
	}
	return err
}

Prevention

Deduplicate aliases by normalized name before Bind
Re-run alias collision checks whenever the normalizer changes
Generate alias tables from a single source of truth

When it happens

Trigger: Two Bind alias entries normalize to the same string but target different canonical flags, e.g. Alias("logLevel","LogLevel") and Alias("log_level","LogFields") under a normalizer that strips underscores, so acceptedAliases[normalized] already holds the first canonical.

Common situations: Bulk alias tables generated from config where several entries collapse to the same normalized name; adding a new alias without checking existing ones; normalizer changes (new version) that newly merge previously distinct names.

Related errors

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