Variants

InvalidValue

Occurs when an [Arg][crate::Arg] has a set of possible values, and the user provides a value which isn't in that set.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind};
let result = Command::new("prog")
    .arg(Arg::new("speed")
        .value_parser(["fast", "slow"]))
    .try_get_matches_from(vec!["prog", "other"]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::InvalidValue);

UnknownArgument

Occurs when a user provides a flag, option, argument or subcommand which isn't defined.

Examples

# use clap_builder as clap;
# use clap::{Command, arg, error::ErrorKind};
let result = Command::new("prog")
    .arg(arg!(--flag "some flag"))
    .try_get_matches_from(vec!["prog", "--other"]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::UnknownArgument);

InvalidSubcommand

Occurs when the user provides an unrecognized Subcommand which meets the threshold for being similar enough to an existing subcommand. If it doesn't meet the threshold, or the 'suggestions' feature is disabled, the more general UnknownArgument error is returned.

Examples

# #[cfg(feature = "suggestions")] {
# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, };
let result = Command::new("prog")
    .subcommand(Command::new("config")
        .about("Used for configuration")
        .arg(Arg::new("config_file")
            .help("The configuration file to use")))
    .try_get_matches_from(vec!["prog", "confi"]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::InvalidSubcommand);
# }

NoEquals

Occurs when the user doesn't use equals for an option that requires equal sign to provide values.

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let res = Command::new("prog")
    .arg(Arg::new("color")
         .action(ArgAction::Set)
         .require_equals(true)
         .long("color"))
    .try_get_matches_from(vec!["prog", "--color", "red"]);
assert!(res.is_err());
assert_eq!(res.unwrap_err().kind(), ErrorKind::NoEquals);

ValueValidation

Occurs when the user provides a value for an argument with a custom validation and the value fails that validation.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, value_parser};
fn is_numeric(val: &str) -> Result<(), String> {
    match val.parse::<i64>() {
        Ok(..) => Ok(()),
        Err(..) => Err(String::from("value wasn't a number!")),
    }
}

let result = Command::new("prog")
    .arg(Arg::new("num")
         .value_parser(value_parser!(u8)))
    .try_get_matches_from(vec!["prog", "NotANumber"]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::ValueValidation);

TooManyValues

Occurs when a user provides more values for an argument than were defined by setting Arg::num_args.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind};
let result = Command::new("prog")
    .arg(Arg::new("arg")
        .num_args(1..=2))
    .try_get_matches_from(vec!["prog", "too", "many", "values"]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::TooManyValues);

TooFewValues

Occurs when the user provides fewer values for an argument than were defined by setting Arg::num_args.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind};
let result = Command::new("prog")
    .arg(Arg::new("some_opt")
        .long("opt")
        .num_args(3..))
    .try_get_matches_from(vec!["prog", "--opt", "too", "few"]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::TooFewValues);

WrongNumberOfValues

Occurs when the user provides a different number of values for an argument than what's been defined by setting Arg::num_args or than was implicitly set by Arg::value_names.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let result = Command::new("prog")
    .arg(Arg::new("some_opt")
        .long("opt")
        .action(ArgAction::Set)
        .num_args(2))
    .try_get_matches_from(vec!["prog", "--opt", "wrong"]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::WrongNumberOfValues);

ArgumentConflict

Occurs when the user provides two values which conflict with each other and can't be used together.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
let result = Command::new("prog")
    .arg(Arg::new("debug")
        .long("debug")
        .action(ArgAction::SetTrue)
        .conflicts_with("color"))
    .arg(Arg::new("color")
        .long("color")
        .action(ArgAction::SetTrue))
    .try_get_matches_from(vec!["prog", "--debug", "--color"]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::ArgumentConflict);

MissingRequiredArgument

Occurs when the user does not provide one or more required arguments.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind};
let result = Command::new("prog")
    .arg(Arg::new("debug")
        .required(true))
    .try_get_matches_from(vec!["prog"]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::MissingRequiredArgument);

MissingSubcommand

Occurs when a subcommand is required (as defined by Command::subcommand_required), but the user does not provide one.

Examples

# use clap_builder as clap;
# use clap::{Command, error::ErrorKind};
let err = Command::new("prog")
    .subcommand_required(true)
    .subcommand(Command::new("test"))
    .try_get_matches_from(vec![
        "myprog",
    ]);
assert!(err.is_err());
assert_eq!(err.unwrap_err().kind(), ErrorKind::MissingSubcommand);
# ;

InvalidUtf8

Occurs when the user provides a value containing invalid UTF-8.

To allow arbitrary data

• Set [Arg::value_parser(value_parser!(OsString))] for argument values
• Set Command::external_subcommand_value_parser for external-subcommand values

Platform Specific

Non-Windows platforms only (such as Linux, Unix, OSX, etc.)

Examples

# #[cfg(unix)] {
# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, ArgAction};
# use std::os::unix::ffi::OsStringExt;
# use std::ffi::OsString;
let result = Command::new("prog")
    .arg(Arg::new("utf8")
        .short('u')
        .action(ArgAction::Set))
    .try_get_matches_from(vec![OsString::from("myprog"),
                                OsString::from("-u"),
                                OsString::from_vec(vec![0xE9])]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::InvalidUtf8);
# }

DisplayHelp

Not a true "error" as it means --help or similar was used. The help message will be sent to stdout.

Note: If the help is displayed due to an error (such as missing subcommands) it will be sent to stderr instead of stdout.

Examples

# #[cfg(feature = "help")] {
# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind};
let result = Command::new("prog")
    .try_get_matches_from(vec!["prog", "--help"]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::DisplayHelp);
# }

DisplayHelpOnMissingArgumentOrSubcommand

Occurs when either an argument or a Subcommand is required, as defined by Command::arg_required_else_help , but the user did not provide one.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind, };
let result = Command::new("prog")
    .arg_required_else_help(true)
    .subcommand(Command::new("config")
        .about("Used for configuration")
        .arg(Arg::new("config_file")
            .help("The configuration file to use")))
    .try_get_matches_from(vec!["prog"]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand);

DisplayVersion

Not a true "error" as it means --version or similar was used. The message will be sent to stdout.

Examples

# use clap_builder as clap;
# use clap::{Command, Arg, error::ErrorKind};
let result = Command::new("prog")
    .version("3.0")
    .try_get_matches_from(vec!["prog", "--version"]);
assert!(result.is_err());
assert_eq!(result.unwrap_err().kind(), ErrorKind::DisplayVersion);

Io

Represents an I/O error. Can occur when writing to stderr or stdout or reading a configuration file.

Format

Represents a Format error (which is a part of Display). Typically caused by writing to stderr or stdout.