uutils/coreutils · error · clap::Error

invalid value

Error message

invalid value

What it means

The ShortcutValueParser builds a clap InvalidValue error when a user-supplied value does not match any possible value (or matches ambiguously). generate_clap_error assembles the clap::Error with the offending arg and value context for a helpful CLI message.

Solutions

1. Use one of the parser's accepted values (check --help output)
2. Rely on the possible-value suggestions shown in the clap error message
3. Add the needed value to the PossibleValue list if you own the utility

Example fix

// before
parse_ref(cmd, &arg, OsStr::new("recursve"))
// after
parse_ref(cmd, &arg, OsStr::new("recursive"))

let allowed = ["recursive", "files0-from", "..."]; // see --help
assert!(allowed.contains(&user_value), "unsupported value: {user_value}");

match ShortcutValueParser::parse_ref(cmd, arg, value) {
    Err(e) if e.kind() == clap::error::ErrorKind::InvalidValue => {
        eprintln!("invalid value {value:?}; see --help");
    }
    r => r?,
}

When it happens

Trigger: Calling parse_ref (or clap value parsing) with a value string that matches none of the parser's PossibleValue entries, e.g. an unknown enum-like CLI option value.

Common situations: Typos in CLI option values; scripts passing wrong-case values; versions where a value was renamed.

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

• InvalidUtf8
• InvalidValue clap error for unmatched argument value
• InvalidUtf8 clap error for non-UTF-8 argument value
• mv-error-backup-might-destroy-source
• mv-error-dangling-symlink

AI-assisted analysis of uutils/coreutils@92995feca2 (2026-09-20). Data as JSON: /api/errors/8b36c103de9bef87. Report an issue: GitHub.

Appendix: source

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

/// `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 92995feca2)