argument for --color must be auto, always, or never, but…

Error message

argument for --color must be auto, always, or never, but found `{arg}`

What it means

This error is thrown by ColorChoice::from_str when the value passed for --color is not exactly 'auto', 'always', or 'never'. It is a strict CLI argument validation: any other spelling (including abbreviations or casing variants) is rejected.

Solutions

Re-run with exactly one of: --color auto, --color always, or --color never
Check the script or alias producing the value for typos or casing differences
Remove the --color flag entirely to use the default (auto) behavior

Example fix

// before
mytool --color Always
// after
mytool --color always

Defensive patterns

Strategy: validation

Validate before calling

fn is_valid_color_choice(s: &str) -> bool {
    matches!(s, "auto" | "always" | "never")
}
// validate argv value before invoking the CLI
if !is_valid_color_choice(&color_value) { eprintln!("--color must be auto, always, or never"); std::process::exit(2); }

Type guard

fn as_color_choice(s: &str) -> Option<ColorChoice> {
    match s {
        "always" => Some(ColorChoice::Always),
        "never" => Some(ColorChoice::Never),
        "auto" => Some(ColorChoice::Auto),
        _ => None,
    }
}

Try / catch

match color_value.parse::<ColorChoice>() {
    Ok(c) => apply(c),
    Err(_) => {
        eprintln!("--color must be auto, always, or never");
        std::process::exit(2);
    }
}

Prevention

Use an enum-backed CLI parser (ValueEnum) so invalid values are rejected with help text
Normalize/trim user input before passing --color
Document the three accepted values in --help
Add a clap possible_values list so shell completion offers valid choices

When it happens

Trigger: from_str is invoked during CLI argument parsing (clap-style) with a --color value that does not match one of the three accepted literals in the match arms.

Common situations: Typos like 'alway' or 'Always'; passing 'true'/'false' or 'ansi'; scripts interpolating an empty or malformed value into --color; users copying a flag value from a different tool that accepts more choices.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

AI-assisted analysis of cross-rs/cross@8c1a8aa4b6 (2026-09-13). Data as JSON: /api/errors/13fe30bb2b9881d5. Report an issue: GitHub.

Appendix: source

Thrown at src/shell.rs:127

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ColorChoice {
    /// force color output
    Always,
    /// force disable color output
    Never,
    /// intelligently guess whether to use color output
    Auto,
}

impl FromStr for ColorChoice {
    type Err = eyre::ErrReport;

    fn from_str(s: &str) -> Result<ColorChoice> {
        match s {
            "always" => Ok(ColorChoice::Always),
            "never" => Ok(ColorChoice::Never),
            "auto" => Ok(ColorChoice::Auto),
            arg => eyre::bail!(
                "argument for --color must be auto, always, or never, but found `{arg}`"
            ),
        }
    }
}

// Should simplify the APIs a lot.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MessageInfo {
    pub color_choice: ColorChoice,
    pub verbosity: Verbosity,
    pub stdout_needs_erase: bool,
    pub stderr_needs_erase: bool,
    pub cross_debug: bool,
    pub has_warned: bool,
}

impl MessageInfo {

View on GitHub (pinned to 8c1a8aa4b6)