# Exit Codes

> Every Testlane exit code, the error name that goes with it, what it means and the error output around it.

Exit codes let a script tell what went wrong without reading the message: a typo in a flag, a project that isn't set up, a branch that doesn't exist or a server that didn't start. Every error also prints a name, like `E_RESOLVE`, so you can find it here and in [Troubleshooting](https://testlane.dev/docs/guides/troubleshooting).

## At a glance

| Code | Name | What it means | For example |
| --- | --- | --- | --- |
| `0` | None | Success | The command did what you asked |
| `1` | `E_INTERNAL` | Something failed that Testlane didn't expect, or a `doctor` check failed | A bug, or `FAIL` in `doctor` |
| `2` | `E_USAGE` | The command doesn't make sense | An unknown flag, a missing `--yes`, a command `start` can't run next to another |
| `3` | `E_CONFIG` | The config is missing or wrong | An unknown project, a file that doesn't validate, no config directory, a repository's `.testlane.toml` you haven't approved |
| `4` | `E_RESOLVE` | The ref or the workspace can't be found | A branch that isn't on `origin`, a ref with no workspace for `sync` or `info` |
| `5` | `E_GIT` | A git or `gh` command failed, or git would lose work | `sync` on a workspace with changes, a lock that times out |
| `6` | `E_SETUP` | `[setup]`, a hook that can block or `start` failed | An install that fails, a server that never opens its port, a program `exec` can't find |

## Error output

Let's start with what an error looks like. It's one line on stderr with the name and the message, often followed by a hint that says what to do:

```
error(E_CONFIG): unknown project 'nope'
hint: known projects: my-project
```

```
error(E_RESOLVE): branch 'nope' does not exist on origin
hint: check the name, or push the ref first
```

```
error(E_USAGE): unsupported shell 'ksh'
hint: one of: bash, zsh, fish
```

The error goes to stderr only, so it never ends up in what a script captures from stdout. With `-v` or `TESTLANE_DEBUG=1`, the stack trace follows the hint.

## Codes from your own commands

Now let's look at the codes Testlane passes on. `run`, `exec`, `shell` and `code` with a terminal editor like `vim` exit with the exit code of what they ran, so a failing test run fails the same way under Testlane:

```bash
testlane my-project feat/login exec -- sh -c 'exit 7'
echo $?
```

```
7
```

Keep in mind that such a code can match one in the table above, so a test runner that exits `2` looks like a usage error. When you need to tell them apart, check stderr for a line that starts with `error(`, which is how Testlane prints its own errors.

## Branching on the code

Finally, let's look at scripts. We recommend branching on the exit code rather than the message, since the wording of a message can change between versions while the codes don't:

```bash
testlane my-project feat/login checkout -q
case $? in
  0) echo "ready" ;;
  4) echo "no such branch, push it first" ;;
  *) echo "something else went wrong" ;;
esac
```

Note that a failing outside tool other than git, like `gh`, can print the name `E_EXTERNAL`, with the same code `5` as `E_GIT`. [Script with Testlane](https://testlane.dev/docs/guides/script-with-testlane) has more patterns, and [Troubleshooting](https://testlane.dev/docs/guides/troubleshooting) has a fix for each error.
