Troubleshooting
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:
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 is the full reference.
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.
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.
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 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.
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 explains.
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:
testlane my-project feat/login checkout --setup
→ worktree ready (reused)
→ running setup
Something failed inside Testlane itself, so it's a bug. Please report it on GitHub 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:
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 explains the trust check.
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.
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:
testlane my-project clean --prune-state --yes
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.
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 has the details.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 explains how Testlane picks ports.
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.Add -v, or --verbose, to print every external command Testlane runs, marked with · on stderr:
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 lists every code and when Testlane uses it.
- Top-level verbs has
doctorandconfig validate. - Workspaces explains where Testlane keeps each workspace and its state.
Install Shell Completions
Add tab completion for bash, zsh or fish, so your shell completes Testlane's verbs, your project names and the workspaces you have.
Use Testlane from an Agent
Let an AI coding agent check out a ref, start a preview, read its logs, stop it and clean up, with the commands, JSON fields and exit codes it needs.