---
# System prepended metadata

title: Taxonomy of errors in nushell

---

# Taxonomy of errors in nushell

## General classes

- Parse errors / syntax errors
    - cases when syntax can not be resolved unambiguously
- Type errors
    - (maybe separate category) Usage of commands and closures with mismatching parameter requirements
    - early binding:
        - problems that can be identified through static analysis and type inference
        - e.g. mismatch between declared input and output types
    - late binding
        - type errors that occur during runtime due to incoming data/dynamic typing 
- Execution errors
    - Value errors
        - input/argument values that are disallowed for a particular operation on a lower level than a type error.
    - System errors
    - missing data when data is expected
    - Failure to complete operation
- flow control "errors" 
    - `break`
    - `continue`
    - `return`
    - (partially Ctrl-C)

## Core properties

### recovery/severity
- unrecoverable inconsistent
    - nushell broke, not safe to continue -> panic/exit immediately
- unrecoverable consistent
    - can not be continued with this working set/scope. the engine may live from a previous state (e.g. syntax error in the repl). exit when evaluating a script.
- recoverable
    - can be caught or thrown in a traditional frame work or transformed in an "errors are values" paradigm
- control flow effect
    - not exposed as an error to the user
### error time
- at "compile" time
    - parse errors
    - type errors through type inference
    - relevant for the IDE experience
- runtime
    - dynamic type errors
    - program errors 
- effectively any time
    - interrupt (through `^C` etc.)
    - Bugs and crashes

## other categories

- Value/Pipeline position
    - input type or pipeline is invalid
    - required argument
    - flag
- has a suggestion/resolution strategy?
- user generated

# Contentious areas at the moment

## Inconsistent use of "type errors"

- partly part of the `ParseError` (e.g.`ParseError::TypeMismatch`)
- we make inconsistent distinction between Type errors in operators, argument position, and pipeline input positions.
- general misuse of Variants

## general messiness in the class of Value errors

- some specialized variants, sometimes well written errors strings, sometimes unclear (or abuse of `ShellError::TypeMismatch`)
- maybe separate out clearly from system related errors like I/O/FileNotFound etc.

## Handling of missing data

- We previously aggresively failed on empty data or had special flag variants. 
    - cumbersome and inconsistent at several places
- `$nothing`/`null` plays a placeholder role for "`void` commands"
- now we silently accept empty data in more places
    - requires more proactive treatment of missing data but causes less surprising runtime failures
- can we recommend consistent strategies for dealing with missingness. 