invalid color mode %q: must be one of: never, auto, always

Error message

invalid color mode %q: must be one of: never, auto, always

What it means

Returned during root command setup (pkg/cmd/root.go:198) when settings.ColorMode is not one of 'never', 'auto', 'always'. ColorMode is bound to both the --color and --colour flags (pkg/cli/environment.go:170-171) and initialized from the NO_COLOR/HELM_COLOR environment variables, where invalid HELM_COLOR values are silently ignored; the error therefore fires when an invalid value arrives via the flag itself or a settings/config source.

Source

Thrown at pkg/cmd/root.go:198

	logSetup(settings.Debug)

	// newRootCmdWithConfig is only called from NewRootCmd. NewRootCmd sets up
	// NewConfiguration without a custom logger. So, the slog default is used. logSetup
	// can change the default logger to the one in the logger package. This happens for
	// the Helm client. This means the actionConfig logger is different from the slog
	// default logger. If they are different we sync the actionConfig logger to the slog
	// current default one.
	if actionConfig.Logger() != slog.Default() {
		actionConfig.SetLogger(slog.Default().Handler())
	}

	// Validate color mode setting
	switch settings.ColorMode {
	case "never", "auto", "always":
		// Valid color mode
	default:
		return nil, fmt.Errorf("invalid color mode %q: must be one of: never, auto, always", settings.ColorMode)
	}

	// Configure color output based on ColorMode setting
	configureColorOutput(settings)

	// Setup shell completion for the color flag
	_ = cmd.RegisterFlagCompletionFunc("color", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
		return []string{"never", "auto", "always"}, cobra.ShellCompDirectiveNoFileComp
	})

	// Setup shell completion for the colour flag
	_ = cmd.RegisterFlagCompletionFunc("colour", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
		return []string{"never", "auto", "always"}, cobra.ShellCompDirectiveNoFileComp
	})

	// Setup shell completion for the namespace flag
	err := cmd.RegisterFlagCompletionFunc("namespace", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
		if client, err := actionConfig.KubernetesClientSet(); err == nil {

View on GitHub (pinned to 2a29f1770b)

Solutions

Use exactly one of: never, auto, or always (lowercase).
If the intent is to disable color in CI, prefer '--color never' or setting NO_COLOR=1.
In SDK code, set settings.ColorMode from a validated constant before building the command tree.

Example fix

# before
helm list --color=yes

# after
helm list --color=always   # or: never / auto

Defensive patterns

Strategy: validation

Validate before calling

# bash: whitelist color modes before invoking helm
case "${COLOR:-auto}" in never|auto|always) ;; *) COLOR=auto ;; esac
helm list --color "$COLOR"

# Go SDK:
switch settings.ColorMode {
case "never", "auto", "always":
default:
    settings.ColorMode = "auto"
}

Prevention

Use NO_COLOR=1 to disable color instead of inventing flag values.
Never forward TERM-derived or numeric color levels into --color; the accepted set is exactly never|auto|always.

When it happens

Trigger: Running any Helm command with '--color=yes', '--colour=1', or any value outside the allowed set; setting ColorMode programmatically on a cli.EnvSettings struct in SDK code; configs that copy a numeric color level (e.g. 'always 3' or '256color') into the flag.

Common situations: Porting scripts from tools that use 'yes/no', 'on/off', or 'true/false' color values; assuming the flag accepts a color count; wrapper scripts forwarding a TERM-derived value into --color.

Related errors

AI-assisted analysis of helm/helm@2a29f1770b (2026-08-15). Data as JSON: /api/errors/e7a04449952c331f. Report an issue: GitHub.