deprecated alias --%s must use independent mode so Cobra can

Error message

deprecated alias --%s must use independent mode so Cobra can emit its warning

What it means

This error is thrown by validateInputCLI when a struct field declares a deprecated normalize-mode alias. Normalize aliases fold into the canonical flag, so Cobra cannot attach its own deprecation warning; deprecated aliases must be independent flags so Cobra's built-in deprecation notice can be emitted. It is a compile-time (registration) error, not a runtime CLI error.

Source

Thrown at shortcuts/common/typed_compile_args.go:359

	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 {
					return fmt.Errorf("trimmed_equal_or_error alias --%s requires string input", alias.Name)
				}
			default:
				return fmt.Errorf("independent alias --%s must declare a supported Conflict", alias.Name)
			}
		default:
			return fmt.Errorf("alias --%s has invalid Mode %q", alias.Name, alias.Mode)
		}
	}
	return nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Remove the deprecated marker from the normalize alias if deprecation is not needed
Change the alias mode to independent (with a supported Conflict) so Cobra can emit its warning
Handle the old flag manually via a Conflict strategy instead of normalize+deprecated

Example fix

// before
NewName string `cli:"--new-name,alias:--old-name;mode=normalize;deprecated"`
// after
NewName string `cli:"--new-name,alias:--old-name;mode=independent;conflict=canonical-wins;deprecated"`

Defensive patterns

Strategy: validation

Validate before calling

for _, f := range fields {
    for _, a := range f.aliases {
        if a.Mode == "normalize" && a.Deprecated {
            return fmt.Errorf("alias --%s: normalize mode cannot be deprecated; use mode=independent", a.Name)
        }
    }
}

Prevention

Pair deprecated aliases only with mode=independent and a supported conflict
Add a unit test per alias tag shape before registering structs
Search the codebase for `mode=normalize` combined with `deprecated` in CI

When it happens

Trigger: Registering a struct whose CLI tag declares an alias with mode normalize plus deprecated:true, e.g. `cli:"--new-name,alias:--old-name;mode=normalize;deprecated"`. compileInput calls validateInputCLI, which checks alias.Mode == typedAliasNormalize && alias.Deprecated.

Common situations: Renaming a flag and keeping the old one as a normalized alias while marking it deprecated; copying an alias definition from an independent-mode example into a normalize-mode field; bulk tag refactors that flipped mode to normalize without dropping deprecated.

Related errors

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