larksuite/cli · error

alias -- for -- conflicts with existing alias for -- after…

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.

Solutions

1. Rename one of the aliases so normalized names stay distinct
2. Map both aliases to the same canonical flag if that was the intent, removing the duplicate declaration
3. Tighten the normalizer (or disable it) so the two names do not collide
4. 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"))

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
}

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
}

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

• alias -- maps to both -- and -- after normalization to
• declares duplicate alias -- for -- after normalization to
• name must not be empty
• alias -- for -- conflicts with registered flag -- after…
• Args field (-- ): json tag is not allowed on a CLI field

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

Appendix: 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)