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

Error message

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

What it means

ColorChoice::from_str parses the --color CLI argument and only accepts 'always', 'never', or 'auto'. Any other string is rejected with a bail! describing the valid choices. This is the canonical color-option validator shared across Cargo's shells.

Solutions

Use exactly one of: auto, always, never.
If accepting user input, validate/normalize to the three accepted values before forwarding to Cargo.
Map boolean input (true->always, false->never) in your wrapper.

Example fix

// before
cargo build --color yes
// after
cargo build --color always

Defensive patterns

Strategy: validation

Validate before calling

fn valid_color(s: &str) -> bool {
    matches!(s, "auto" | "always" | "never")
}
// before forwarding:
if !valid_color(&val) {
    eprintln!("--color must be auto|always|never");
}

Type guard

null

Try / catch

null

Prevention

Constrain color option input with an enum/clap value_parser.
Normalize boolean inputs to always/never in wrappers.

When it happens

Trigger: Passing `--color yes`, `--color true`, `--color=1`, or any non-recognized value to a Cargo (or cargo-util-terminal based) command that forwards to this FromStr impl.

Common situations: Scripts/aliases that pass 'yes'/'on'/'force' instead of 'always'; CI config typos; tooling that assumes boolean-style values.

Related errors

AI-assisted analysis of rust-lang/cargo@eb98b54bc9 (2026-08-11). Data as JSON: /api/errors/dd2fd85514692b21. Report an issue: GitHub.

Appendix: source

Thrown at crates/cargo-util-terminal/src/shell.rs:593

    fn to_anstream_color_choice(self) -> anstream::ColorChoice {
        match self {
            ColorChoice::Always => anstream::ColorChoice::Always,
            ColorChoice::Never => anstream::ColorChoice::Never,
            ColorChoice::CargoAuto => anstream::ColorChoice::Auto,
        }
    }
}

impl std::str::FromStr for ColorChoice {
    type Err = anyhow::Error;
    fn from_str(color: &str) -> Result<Self, Self::Err> {
        let cfg = match color {
            "always" => ColorChoice::Always,
            "never" => ColorChoice::Never,

            "auto" => ColorChoice::CargoAuto,

            arg => anyhow::bail!(
                "argument for --color must be auto, always, or \
                     never, but found `{}`",
                arg
            ),
        };
        Ok(cfg)
    }
}

fn supports_color(choice: anstream::ColorChoice) -> bool {
    match choice {
        anstream::ColorChoice::Always
        | anstream::ColorChoice::AlwaysAnsi
        | anstream::ColorChoice::Auto => true,
        anstream::ColorChoice::Never => false,
    }
}

View on GitHub (pinned to eb98b54bc9)