What causes "alias --%s has invalid Mode %q" in larksuite/cli?

Set mode=normalize or mode=independent

alias --%s has invalid Mode %q

Error message

alias --%s has invalid Mode %q

What it means

Thrown by validateInputCLI when an alias declares a Mode that is neither normalize nor independent. Alias mode is an enum; any other value makes the tag grammar invalid and the struct fails to compile into a CLI argument parser.

Source

Thrown at shortcuts/common/typed_compile_args.go:372

		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
}

type schemaTag struct {
	required     bool
	optional     bool
	nullable     *bool
	defaultValue typedInputDefault
	enum         []string
	format       string
	minLength    *int
	maxLength    *int
	minimum      *float64
	maximum      *float64
	minItems     *int
	maxItems     *int

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Set mode=normalize or mode=independent
Fix the spelling of the mode keyword
Check the alias tag grammar in the package docs/tests for valid values

Example fix

// before
Name string `cli:"--name,alias:--nom;mode=replace;conflict=canonical-wins"`
// after
Name string `cli:"--name,alias:--nom;mode=independent;conflict=canonical-wins"`

Defensive patterns

Strategy: validation

Validate before calling

var validModes = map[string]bool{"normalize": true, "independent": true}
if !validModes[a.Mode] {
    return fmt.Errorf("alias --%s: mode %q invalid", a.Name, a.Mode)
}

Prevention

Use named constants for modes instead of string literals in tags
Grep tags for `mode=` during review and validate against the enum
Centralize alias tag construction in helpers

When it happens

Trigger: A tag like `alias:--old;mode=fold` or a typo such as `mode=normalized`; compileInput -> validateInputCLI's default branch formats the invalid Mode value into the message.

Common situations: Typos in the mode keyword; guessing mode names instead of using the documented enum; edits after renaming mode constants.

Related errors

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