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.

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

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

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

Appendix: 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)