# Troubleshooting

> Find out what went wrong when a Testlane command fails, from the error it printed or the symptom you see, and how to fix it.

When a command fails, this page helps you find out why and fix it. Testlane prints one `error(E_…)` line for every failure, often with a `hint:` that names the fix, and exits with a code of its own, so start from the error code when you have one, or from the symptom when you don't.

## Start with doctor

`doctor` checks your tools, your config directory and every project you've set up, in one go:

```bash
testlane doctor
```

```
OK   git version: git 2.50.1
OK   gh (github cli): authenticated
OK   config dir: /home/you/.testlane
OK   state dir: /home/you/.local/state/testlane
OK   project my-project: config: schema-valid
OK   project my-project: repo: bare repo at /home/you/dev/testlane/my-project/repo
OK   project my-project: fetch refspec: remote.origin.fetch configured
```

Each line is one check, marked `OK`, `WARN` or `FAIL`. `OK` needs nothing from you. `WARN` means the project still works, but something is limited, like pull request titles and push-back without `gh`. `FAIL` means something is broken, and `doctor` exits with `1` when any check fails, so you can run it in CI too.

It checks your `git` version (2.38 or later), whether `gh` is installed and signed in, that the config directory can be read and the state directory written, and whether any lock was left behind. For each project, it checks the project file, the clone and its fetch refspec, the editor, `core.hooksPath`, any command that has the name of a built-in verb, whether its workspaces still match what's on disk, and the repository's `.testlane.toml`, if it ships one.

## Errors by code

Each error prints one line on stderr, an optional `hint:` and exits with its code. [Exit codes](https://testlane.dev/docs/cli/exit-codes) is the full reference.

::accordion
  :::accordion-item{label="E_USAGE, exit 2"}
  A flag or an argument is wrong, or missing. The message names it, and the hint usually lists what Testlane expected:

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

  It's also what `clean` and `rm` exit with when they can't ask you to confirm, like in a script, so add `--yes` there.
  :::

  :::accordion-item{label="E_CONFIG, exit 3"}
  Testlane can't find a project's file, or can't read it:

  ```
  error(E_CONFIG): unknown project 'my-projct'
  hint: known projects: my-project — did you mean 'my-project'?
  ```

  Check the name against `testlane projects`, or create the project with `testlane setup`. When the file exists but doesn't parse or has a wrong key, `testlane config validate` names the file, the key and what's wrong with it. `testlane config path` prints the config directory Testlane uses, which is worth checking when `TESTLANE_CONFIG_DIR` is set in your shell.
  :::

  :::accordion-item{label="E_RESOLVE, exit 4"}
  Testlane fetched the ref, and it isn't there:

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

  It's usually a typo, or a branch that only exists in your own clone, so push it or give a commit SHA instead. [Refs](https://testlane.dev/docs/concepts/refs) lists the forms a ref can take. `sync` and `diff` exit with it too when the workspace doesn't exist yet, so run `checkout` first.
  :::

  :::accordion-item{label="E_GIT, exit 5"}
  A `git` or `gh` command failed, and its own error is printed with it. The usual causes are no network on a first checkout, since the clone fetches what it needs as it goes, a sign-in that has expired, or a clone that's lost its fetch refspec. `doctor` reports a missing refspec as `FAIL` and prints the `git config` command that restores it.

  `sync` exits with it too when a workspace has uncommitted changes, as [Refresh a workspace](https://testlane.dev/docs/guides/refresh-a-workspace) explains.
  :::

  :::accordion-item{label="E_SETUP, exit 6"}
  Your `[setup]` install, a hook or a command `start` launched failed, and Testlane prints what failed:

  ```
  error(E_SETUP): setup command failed (exit 1)
  ```

  Fix the command, then run setup again in the same workspace:

  ```bash
  testlane my-project feat/login checkout --setup
  ```

  ```
  → worktree ready (reused)
  → running setup
  ```
  :::

  :::accordion-item{label="E_INTERNAL, exit 1"}
  Something failed inside Testlane itself, so it's a bug. Please report it on [GitHub](https://github.com/uxfront-com/testlane/issues) with the command you ran and its output with `-v`.

  Note that `doctor` also exits with `1` when one of its checks fails, without an `E_INTERNAL` line.
  :::
::

## Common situations

These come up often, and most of them don't have an error code of their own:

::accordion
  :::accordion-item{label="A repository's .testlane.toml isn't trusted"}
  ```
  error(E_CONFIG): my-project:.testlane.toml is not trusted
  hint: testlane config trust my-project
  ```

  The repository ships a `.testlane.toml`, and you haven't approved it on this machine yet, or it changed since you did, when the error ends in "changed since you trusted it". Run `testlane config trust my-project` on a terminal to read it and approve it, or pass `--yes` where you trust the repository's default branch. `doctor` shows the same state in its `repo file` check: `WARN` when the file is untrusted or changed, or gone upstream with an approval still stored, and `FAIL` when the stored approval no longer validates. [Ship a config with your repo](https://testlane.dev/docs/guides/ship-a-config-with-your-repo#approve-it) explains the trust check.
  :::

  :::accordion-item{label="clean skipped a workspace"}
  ```
  warning: skipping feat-login: worktree is dirty (use --force)
  ```

  The workspace has uncommitted changes, and Testlane won't throw them away. Commit or stash them, or pass `--force` if you're sure you want them gone.
  :::

  :::accordion-item{label="A workspace shows missing"}
  ```
  SLUG         KIND    BRANCH       STATUS   PORT  AGE  LAST USED
  feat-search  branch  feat/search  missing  4160  2m   1m
  ```

  Its directory was deleted outside Testlane. Drop the entry Testlane still keeps for it:

  ```bash
  testlane my-project clean --prune-state --yes
  ```
  :::

  :::accordion-item{label="A branch is already checked out"}
  ```
  error(E_GIT): 'feat/search' is already checked out in another workspace
  hint: use that workspace, or remove it first with `testlane <project> <ref> rm`
  ```

  Git lets a branch live in only one worktree at a time. Use the workspace that has it, or remove that one first. To look at the same code in a second workspace, check out the commit SHA instead of the branch name.
  :::

  :::accordion-item{label="Hooks behave strangely with husky or core.hooksPath"}
  `doctor` warns when a repository sets `core.hooksPath`. A relative hooks path, as husky writes it, can resolve wrongly from a worktree, and `pnpm install` can try to install hooks into the bare clone. Testlane leaves your repository as it is, so [Known caveats](https://testlane.dev/docs/concepts/workspaces#known-caveats) has the details.
  :::

  :::accordion-item{label="Port already in use"}
  Something outside Testlane holds the workspace's port. `start` stops with `E_SETUP` and names the port, with an `lsof` command in its hint that shows what holds it. `run` doesn't check, so your server fails to bind instead.

  Free the port, or move the project's ports with `base_port`. For one `run`, `--port` uses another port. [Run dev servers in parallel](https://testlane.dev/docs/guides/run-dev-servers-in-parallel) explains how Testlane picks ports.
  :::

  :::accordion-item{label="start gives up before the server is ready"}
  `start` returns once the workspace's port accepts connections, and it stops with `E_SETUP` when the command exits first or the port isn't ready within `--timeout`, 300 seconds by default. Read the end of the log with `testlane my-project feat/login logs`, and check that your server listens on `127.0.0.1` at `{port}`. A slow first build may need a longer `--timeout`.
  :::

  :::accordion-item{label="A command fails and you can't tell why"}
  Add `-v`, or `--verbose`, to print every external command Testlane runs, marked with `·` on stderr:

  ```bash
  testlane my-project feat/login checkout -v
  ```

  ```
  → fetching origin/feat/login
  · git -C /home/you/dev/testlane/my-project/repo fetch --no-tags origin --end-of-options feat/login
  · git -C /home/you/dev/testlane/my-project/repo worktree add /home/you/dev/testlane/my-project/trees/feat-login -B feat/login --track origin/feat/login
  → worktree ready: /home/you/dev/testlane/my-project/trees/feat-login
  ```

  To see the plan without running it, use `--dry-run` instead, like `testlane my-project feat/login run dev --dry-run`. `-q`, or `--quiet`, does the opposite of `-v`: it hides the progress lines, so only the result and any warnings are left.
  :::
::

## Where to go next

Here's where to go from here:

- [Exit codes](https://testlane.dev/docs/cli/exit-codes) lists every code and when Testlane uses it.
- [Top-level verbs](https://testlane.dev/docs/cli/top-level-verbs) has `doctor` and `config validate`.
- [Workspaces](https://testlane.dev/docs/concepts/workspaces) explains where Testlane keeps each workspace and its state.
