Guide
Fixing git worktree errors: "already checked out", "already exists" and stale worktrees
git worktree errors are short and cryptic, but there are only a handful of them, and each one has a one-line fix once you know what git is protecting.
"fatal: 'main' is already checked out at …" (or "is already used by worktree at …")
Git allows a branch in only one worktree at a time, so two folders can never commit to the same branch without knowing it. You asked for a branch that is already open somewhere else.
- Want a new line of work? Create a new branch: git worktree add ../app-task -b task main.
- Only need to look at the code? Detach: git worktree add --detach ../app-look main.
- Think the other worktree is gone? Run git worktree list, then git worktree prune if its folder no longer exists.
"fatal: '../app-task' already exists"
The target folder exists on disk, and git will not write into a non-empty directory. Usually it is a leftover from an earlier worktree that was removed from git but not from disk.
Pick another path, or delete the folder if you are sure nothing in it matters, then run the add again.
"… is a missing but already registered worktree"
The folder was deleted by hand (or lived on a drive that is not mounted) but git still has it registered. The message tells you the options: git worktree prune to forget missing worktrees, or add -f to reuse the path anyway.
The habit that prevents it: remove worktrees with git worktree remove, not with the file manager.
A worktree that will not go away
- Uncommitted changes: git worktree remove refuses. Commit or stash them, or add --force to discard them.
- Locked: prune and remove skip locked worktrees. git worktree unlock <path> first.
- Branch still exists after removal: that is by design. git branch -d <branch> once it is merged, -D to discard it.
Why this matters more with agents
Running several coding agents means creating and deleting worktrees many times a day, which is exactly how the stale-registration and leftover-folder errors pile up. Scripting the add and remove — or using a workspace that creates and cleans worktrees per session — removes the whole category.
Questions
- Can I force two worktrees onto the same branch?
- git worktree add --force allows it, but then two folders can commit to one branch without knowing about each other — the problem worktrees exist to prevent. Use a second branch instead.
- Is it safe to delete a worktree folder by hand?
- Nothing is lost from the repository, but git keeps the registration until you run git worktree prune. git worktree remove does both in one step.