alibaba/open-code-review · error

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

Error message

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

What it means

validateColorMode validates the --color flag, which controls ANSI color output. Only the exact values auto, always, and never are accepted; anything else (including intuitive aliases like yes, true, or on) is rejected so a typo is reported instead of silently treated as auto.

Source

Thrown at cmd/opencodereview/color.go:48

)

// addColorFlags registers the color control. It is persistent on the root
// command so every subcommand inherits identical behavior, and so
// `ocr --color=never review` and `ocr review --color=never` are equivalent.
func addColorFlags(cmd *cobra.Command) {
	cmd.PersistentFlags().StringVar(&colorMode, "color", colorModeAuto,
		"when to emit ANSI color: auto (only when stdout is a terminal), always, or never")
	cmd.RegisterFlagCompletionFunc("color", completeEnum(colorModeAuto, colorModeAlways, colorModeNever))
}

// validateColorMode rejects unknown --color values instead of silently treating
// them as auto, so a typo like --color=yes is reported rather than ignored.
func validateColorMode(mode string) error {
	switch mode {
	case colorModeAuto, colorModeAlways, colorModeNever:
		return nil
	default:
		return fmt.Errorf("invalid --color value %q: must be one of auto, always, never", mode)
	}
}

// resolveColor decides whether ANSI sequences may be written to stdout.
//
// Precedence, highest first:
//  1. --color=never         → off
//  2. --color=always        → on, even into a pipe (for `| less -R`)
//  3. TERM=dumb              → off
//  4. stdout is a terminal  → on, otherwise off
func resolveColor() bool {
	if colorMode == colorModeNever {
		return false
	}
	if colorMode == colorModeAlways {
		return true
	}
	if strings.EqualFold(os.Getenv("TERM"), "dumb") {

View on GitHub (pinned to 5cf97d0d15)

Solutions

1. Use one of the exact values: `--color=auto`, `--color=always`, or `--color=never`.
2. Map legacy values in scripts: replace `--color=yes` with `--color=always` and `--color=no` with `--color=never`.
3. If the value comes from an environment variable, quote and normalize it: `--color="${OCR_COLOR:-auto}"` with OCR_COLOR validated beforehand.
4. Run `ocr --help` to confirm the accepted values.

Example fix

// before
ocr review --color=yes
// after
ocr review --color=always

// shell: normalize and validate the color value before invoking ocr
case "$OCR_COLOR" in
  auto|always|never) ;;
  yes|true|1) OCR_COLOR=always ;;
  no|false|0) OCR_COLOR=never ;;
  *) echo "invalid --color: $OCR_COLOR (use auto|always|never)"; exit 2 ;;
esac

out, err := cmd.CombinedOutput()
if err != nil && strings.Contains(string(out), "invalid --color value") {
	return fmt.Errorf("fix --color flag: %s", out)
}

When it happens

Trigger: Running any ocr command with `--color <value>` where value is not exactly `auto`, `always`, or `never` — e.g. `--color=yes`, `--color=true`, `--color=ALWAYS`, `--color=never ` (trailing space via script variable).

Common situations: Porting CI scripts from tools that accept --color=yes/--color=force; typos like --color=alwys; uppercase values in shell variables sourced from config; spaces from unquoted environment variables.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

• --max-tokens-budget must be a non-negative integer (0 means
• --effort: %w
• invalid --format value %q: must be 'text' or 'json'
• "%q %s" (+ positional signature, valid values, usage line, e
• read background file %q: %w

AI-assisted analysis of alibaba/open-code-review@5cf97d0d15 (2026-09-02). Data as JSON: /api/errors/5f611d01f59e3dce. Report an issue: GitHub.