Error Handling Reference

This page lists every error type clish can produce, how they are formatted, and how to handle them.

ErrorKind variants

Variant	Description	Triggered when
UnknownCommand	Command name not found	User types a command that does not exist
UnknownOption	Invalid flag or option	User passes an unrecognized --name or -x
MissingValue	Named option without a value	User passes --env but provides no value
MissingArgument	Required positional not provided	User omits a required Pos<T> argument
InvalidValue	Value failed type parsing	User passes abc where a u16 is expected
InvalidChoice	Value not in allowed choices	User passes a value not in the choices list
Conflict	Mutually exclusive options used together	User passes two parameters that conflicts_with each other
Requires	Missing prerequisite option	User passes a parameter that requires another which is absent
OneshotWithOtherCommands	Oneshot mode with multiple commands	app!(cmd) is used but multiple commands are registered

Error output format

Errors are printed to stderr with structured formatting:

Unknown command

error: unknown command 'deplyo'
  |
1 | myapp deplyo
  |        ^^^^^^
  |
  = hint: run 'myapp --help' for available commands

Unknown option

error: unknown argument --invalid
  |
1 | myapp deploy --invalid
  |              ^^^^^^^^^
  |
  = hint: run 'myapp deploy --help' for more information

Missing value

error: missing value for option --env
  |
1 | myapp deploy --env
  |              ^^^^^
  |
  = note: --env expects a value

Missing argument

error: missing required argument <target>
  |
1 | myapp deploy
  |             ^
  |
  = hint: run 'myapp deploy --help' for more information

Invalid value

error: invalid value 'abc': expected u16
  |
1 | myapp serve --port abc
  |                    ^^^
  |
  = hint: run 'myapp serve --help' for more information

Invalid choice

error: invalid choice 'trace': expected one of debug, info, error
  |
1 | myapp log --level trace
  |                   ^^^^^
  |
  = hint: run 'myapp log --help' for more information

Conflict

error: conflicting arguments --verbose and --quiet cannot be used together
  |
1 | myapp build --verbose --quiet
  |               ^^^^^^^^^^^^^^^
  |
  = hint: run 'myapp build --help' for more information

Requires

error: missing required argument --output requires --format
  |
1 | myapp build --output out.txt
  |               ^^^^^^
  |
  = hint: run 'myapp build --help' for more information

Error style fields

All error elements can be customized via AppStyles:

Field	Default	What it styles
error_label	[bold red]	The "error" prefix
error_kind	(none)	Error type identifier
error_token	[yellow]	Problematic tokens in error messages
error_pipes	[bold blue]	Source line and pipes
error_highlight	[bold red]	Caret highlighting
hint	[bold cyan]	Hint and note messages

Compile-time vs runtime errors

Compile-time errors

These prevent your project from building:

Error	Cause
Option<Vec<T>> is redundant	Use Vec<T> instead
Option<bool> is not supported	Use bool for flags
Only one Pos<Vec<T>> allowed	Multiple variadic positionals are not permitted
Pos<Vec<T>> must be last	Variadic positional must be the final positional parameter
Unsupported parameter type	Use Pos<T>, Named<T>, or bool
Duplicate short flag	The same short character is used by multiple parameters

Runtime errors

These occur during command execution when user input is invalid:

Error category	Examples
Missing required arguments	Omitted Pos<T> or Named<T>
Invalid type conversions	Passing text where a number is expected
Choice constraint violations	Values not in the choices list
Conflict rule violations	Mutually exclusive parameters used together
Requires rule violations	Prerequisite parameters missing

Custom error handling in command functions

Your command function can return Result<(), String> to produce custom errors:

#[command]
fn deploy(target: Pos<String>) -> Result<(), String> {
    if target.0.is_empty() {
        return Err("target cannot be empty".to_string());
    }
    // ... command logic
    Ok(())
}

The error string is printed using the standard error formatting pipeline, so your custom styles apply.