independent alias --%s must declare a supported Conflict

Error message

independent alias --%s must declare a supported Conflict

What it means

Thrown by validateInputCLI when an independent-mode alias declares a Conflict value outside the supported set (canonical-wins, error-if-both, trimmed_equal_or_error). The compiler requires independent aliases to state an explicit, supported conflict policy because both flags can be supplied independently.

Source

Thrown at shortcuts/common/typed_compile_args.go:369

		}
		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
}

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

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Set conflict to one of: canonical-wins, error-if-both, trimmed_equal_or_error
Fix spelling of the conflict keyword
If the alias should fold silently, use mode=normalize instead of independent

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

var validConflicts = map[string]bool{"canonical-wins": true, "error-if-both": true, "trimmed_equal_or_error": true}
if a.Mode == "independent" && !validConflicts[a.Conflict] {
    return fmt.Errorf("alias --%s: conflict %q not supported", a.Name, a.Conflict)
}

Prevention

Keep a const list of supported conflict values and reference it in tags
Lint CLI tags for known keyword spellings
Always declare Conflict when using mode=independent

When it happens

Trigger: A tag like `alias:--old;mode=independent;conflict=some-strategy` (unknown name), or mode=independent with no conflict at all; compileInput -> validateInputCLI hits the default branch of the Conflict switch.

Common situations: Typo in the conflict keyword (e.g. canoncial-wins); inventing a strategy name that exists in another framework; switching mode from normalize (which forbids Conflict) to independent without adding a valid Conflict.

Related errors

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