uutils/coreutils · error · clap::Error

InvalidValue clap error for unmatched argument value

Error message

InvalidValue clap error for unmatched argument value

What it means

`generate_clap_error` in the shortcut (prefix-matching) value parser builds a clap `InvalidValue` error when the provided value does not match any possible value (or is ambiguous/unmatched) for the argument. It attaches the offending argument and the invalid value plus the list of valid possibilities.

Source

Thrown at src/uucore/src/lib/features/parser/shortcut_value_parser.rs:37

/// `ShortcutValueParser` is similar to clap's `PossibleValuesParser`: it verifies that the value is
/// from an enumerated set of `PossibleValue`.
///
/// Whereas `PossibleValuesParser` only accepts exact matches, `ShortcutValueParser` also accepts
/// shortcuts as long as they are unambiguous.
impl ShortcutValueParser {
    /// Create a new `ShortcutValueParser` from a list of `PossibleValue`.
    pub fn new(values: impl Into<Self>) -> Self {
        values.into()
    }

    fn generate_clap_error(
        &self,
        cmd: &clap::Command,
        arg: Option<&clap::Arg>,
        value: &str,
        possible_values: &[&PossibleValue],
    ) -> clap::Error {
        let mut err = clap::Error::new(ErrorKind::InvalidValue).with_cmd(cmd);

        if let Some(arg) = arg {
            err.insert(
                ContextKind::InvalidArg,
                ContextValue::String(arg.to_string()),
            );
        }

        err.insert(
            ContextKind::InvalidValue,
            ContextValue::String(value.to_string()),
        );

        err.insert(
            ContextKind::ValidValue,
            ContextValue::Strings(self.0.iter().map(|x| x.get_name().to_string()).collect()),
        );

View on GitHub (pinned to 325183372a)

Solutions

1. Use one of the exact valid values listed in the error
2. Check spelling/case of the value
3. If using an abbreviation, lengthen it so it matches exactly one possible value

Example fix

# before
prog --color automn   # ambiguous/invalid
# after
prog --color auto     # or the full value: autumn

const VALID: &[&str] = &["auto", "always", "never"];
fn value_ok(v: &str) -> bool {
    VALID.iter().filter(|x| x.starts_with(v)).count() == 1
}

fn is_exact_match(v: &str, opts: &[&str]) -> Option<&str> {
    opts.iter().find(|o| **o == v).copied()
}

match parse_arg(value) {
    Err(e) if e.kind() == clap::error::ErrorKind::InvalidValue => {
        eprintln!("bad value; use one of: auto, always, never");
        default_value()
    }
    other => other?,
}

When it happens

Trigger: Passing a value that doesn't prefix-match any of the parser's `PossibleValue`s, or one that matches multiple values ambiguously, to an argument using ShortcutValueParser (e.g. abbreviated flag values).

Common situations: Typo in an abbreviated enum-like CLI value, abbreviations becoming ambiguous after new values are added in a version update, case-mismatched input.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• InvalidUtf8 clap error for non-UTF-8 argument value
• realpath-invalid-empty-operand

AI-assisted analysis of uutils/coreutils@325183372a (2026-08-31). Data as JSON: /api/errors/8f091b009df9087d. Report an issue: GitHub.