Git Worktree Troubleshooting

Git worktrees are reliable, but certain operations can produce confusing error messages. Below is a list of the most common issues. Click through for detailed explanations and step-by-step fixes.

"cannot delete branch used by worktree"

Git refuses to delete a branch because it is still checked out in a worktree. Learn how to remove the worktree first and then safely delete the branch.

"fatal: this operation must be run in a work tree"

You ran a command inside a bare repository, a .git directory, or a corrupted checkout. This guide covers all the common causes and their fixes.

"fatal: not a git repository"

The .git file in your worktree is broken or points to a missing location. Learn how to diagnose and repair the link.

"fatal: invalid reference"

Git cannot find the branch or commit you specified when creating a worktree. Check spelling, fetch remote branches, or create the branch first.

"fatal: 'branch' is already checked out at 'path'"

Git prevents the same branch from being checked out in two worktrees simultaneously. Either use a different branch or remove the existing worktree first.

Dirty worktree preventing operations

Git refuses to remove or switch because of uncommitted changes. Learn how to stash, commit, or force your way through safely.

General Tips

Run git worktree list to see all worktrees and their checked-out branches.
Run git worktree prune regularly to clean up references to worktrees whose directories have been deleted.
Use git worktree remove <path> instead of rm -rf to properly remove a worktree.
If a worktree is on a removable drive, use git worktree lock <path> so Git does not prune it while the drive is disconnected.