{"record":{"id":"c73b8c98e1270eff","repo":"larksuite/cli","slug":"deprecated-alias-s-must-use-independent-mode-so","errorCode":null,"errorMessage":"deprecated alias --%s must use independent mode so Cobra can emit its warning","messagePattern":"deprecated alias --(.+?) must use independent mode so Cobra can emit its warning","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"shortcuts/common/typed_compile_args.go","lineNumber":359,"sourceCode":"\tseenAliases := make(map[string]struct{})\n\tfor i, alias := range field.cli.Aliases {\n\t\tif !aliasNamePattern.MatchString(alias.Name) {\n\t\t\treturn fmt.Errorf(\"alias[%d] name %q is invalid\", i, alias.Name)\n\t\t}\n\t\tif alias.Name == field.name {\n\t\t\treturn fmt.Errorf(\"alias[%d] duplicates canonical flag --%s\", i, field.name)\n\t\t}\n\t\tif _, duplicate := seenAliases[alias.Name]; duplicate {\n\t\t\treturn fmt.Errorf(\"duplicate alias --%s\", alias.Name)\n\t\t}\n\t\tseenAliases[alias.Name] = struct{}{}\n\t\tswitch alias.Mode {\n\t\tcase typedAliasNormalize:\n\t\t\tif alias.Conflict != \"\" {\n\t\t\t\treturn fmt.Errorf(\"normalize alias --%s cannot declare Conflict\", alias.Name)\n\t\t\t}\n\t\t\tif alias.Deprecated {\n\t\t\t\treturn fmt.Errorf(\"deprecated alias --%s must use independent mode so Cobra can emit its warning\", alias.Name)\n\t\t\t}\n\t\tcase typedAliasIndependent:\n\t\t\tswitch alias.Conflict {\n\t\t\tcase typedAliasCanonicalWins, typedAliasErrorIfBoth:\n\t\t\tcase typedAliasTrimmedEqualOrError:\n\t\t\t\tif indirectKind(field.valueType) != reflect.String {\n\t\t\t\t\treturn fmt.Errorf(\"trimmed_equal_or_error alias --%s requires string input\", alias.Name)\n\t\t\t\t}\n\t\t\tdefault:\n\t\t\t\treturn fmt.Errorf(\"independent alias --%s must declare a supported Conflict\", alias.Name)\n\t\t\t}\n\t\tdefault:\n\t\t\treturn fmt.Errorf(\"alias --%s has invalid Mode %q\", alias.Name, alias.Mode)\n\t\t}\n\t}\n\treturn nil\n}\n","sourceCodeStart":341,"sourceCodeEnd":377,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/shortcuts/common/typed_compile_args.go#L341-L377","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nNewName string `cli:\"--new-name,alias:--old-name;mode=normalize;deprecated\"`\n// after\nNewName string `cli:\"--new-name,alias:--old-name;mode=independent;conflict=canonical-wins;deprecated\"`","handlingStrategy":"validation","validationCode":"for _, f := range fields {\n    for _, a := range f.aliases {\n        if a.Mode == \"normalize\" && a.Deprecated {\n            return fmt.Errorf(\"alias --%s: normalize mode cannot be deprecated; use mode=independent\", a.Name)\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["cli","flags","alias","deprecated","validation"],"backgroundTag":"invalid-flag-alias-configuration","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}