larksuite/cli · error

alias[%d] duplicates canonical flag --%s

Error message

alias[%d] duplicates canonical flag --%s

What it means

Validation in validateInputCLI: an alias spec re-declares the canonical flag it belongs to as one of its aliases. Aliases must differ from their canonical flag name.

Source

Thrown at shortcuts/common/typed_compile_args.go:347

			return fmt.Errorf("encoding comma_or_repeated does not allow nullable/nonnullable")
		}
	case typedEncodingJSON:
		if kind != reflect.Slice && kind != reflect.Array && kind != reflect.Struct && kind != reflect.Map && kind != reflect.Interface {
			return fmt.Errorf("encoding json requires array, object, oneOf, or custom JSON input")
		}
		if isNilCapable(field.valueType) && field.nullable == nil && !field.shapeExplicit && !shapeExplicitlyNullable(field.shape) {
			return fmt.Errorf("nil-capable encoding=json input must declare nullable or nonnullable")
		}
	default:
		return fmt.Errorf("unknown CLI encoding %q", field.cli.Encoding)
	}
	seenAliases := make(map[string]struct{})
	for i, alias := range field.cli.Aliases {
		if !aliasNamePattern.MatchString(alias.Name) {
			return fmt.Errorf("alias[%d] name %q is invalid", i, alias.Name)
		}
		if alias.Name == field.name {
			return fmt.Errorf("alias[%d] duplicates canonical flag --%s", i, field.name)
		}
		if _, duplicate := seenAliases[alias.Name]; duplicate {
			return fmt.Errorf("duplicate alias --%s", alias.Name)
		}
		seenAliases[alias.Name] = struct{}{}
		switch alias.Mode {
		case typedAliasNormalize:
			if alias.Conflict != "" {
				return fmt.Errorf("normalize alias --%s cannot declare Conflict", alias.Name)
			}
			if alias.Deprecated {
				return fmt.Errorf("deprecated alias --%s must use independent mode so Cobra can emit its warning", alias.Name)
			}
		case typedAliasIndependent:
			switch alias.Conflict {
			case typedAliasCanonicalWins, typedAliasErrorIfBoth:
			case typedAliasTrimmedEqualOrError:
				if indirectKind(field.valueType) != reflect.String {

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Remove the redundant alias entry; the canonical flag is already registered.
2. Choose a genuinely different short/alternate name for the alias.
3. After field renames, audit cli tags so the old name stays only as an alias, not both.

Example fix

// before
Verbose bool `schema:"optional" cli:"alias=verbose"`
// after
Verbose bool `schema:"optional" cli:"alias=v"`

func aliasNotCanonical(fieldName, alias string) error {
	if alias == fieldName {
		return fmt.Errorf("alias %q duplicates the canonical flag; remove it", alias)
	}
	return nil
}

When it happens

Trigger: A cli tag declares alias=X on a field whose canonical name is X (e.g. field `verbose` with tag cli:"alias=verbose"); the alias.Name == field.name check fails.

Common situations: Adding an alias list and accidentally repeating the canonical name; refactoring a field rename so a former alias became the canonical name while still listed as an alias.

Related errors

• duplicate alias --%s
• alias[%d] name %q is invalid
• normalize alias --%s cannot declare Conflict
• encoding comma_or_repeated requires an array or slice
• encoding comma_or_repeated only supports string or integer a

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