Git: Cannot Delete Branch Used by a Worktree

git worktrees

Git refuses to delete a branch while any worktree has it checked out. Find the worktree with git worktree list, remove it with git worktree remove <path> (or git worktree prune if the folder is already gone), then delete the branch.

The error, verbatim:

error: Cannot delete branch 'feature/auth' checked out at '/Users/you/code/myrepo-auth'

-D does not help. It overrides the unmerged-work check, not this one.

Why git refuses

A branch is a pointer, and a checked-out branch is a pointer some working directory is actively holding. Delete it out from under that directory and the worktree is left on a branch that no longer exists, with an index and a HEAD referring to nothing. Git blocks it for the same reason it blocks checking out one branch in two worktrees at once.

The message names the path. That path is the whole diagnosis: either the folder is still there and still in use, or it isn’t there at all and git hasn’t been told.

Case 1: the worktree still exists

git worktree list
/Users/you/code/myrepo       eae19c2 [main]
/Users/you/code/myrepo-auth  eae19c2 [feature/auth]

If you’re done with it, merge anything you want to keep, then remove the worktree and the branch:

git -C ../myrepo-auth status      # check nothing uncommitted is in there
git worktree remove ../myrepo-auth
git branch -d feature/auth

If you want to keep the worktree and only free the branch name, move that worktree onto a different branch instead:

git -C ../myrepo-auth switch -c feature/auth-v2
git branch -d feature/auth

Case 2: the path in the error doesn’t exist

This is the common one. Someone (often you, often an agent, often rm -rf) deleted the worktree folder directly. Git still has the record, and the record still claims the branch. git worktree list gives it away:

/Users/you/code/myrepo-auth  eae19c2 [feature/auth] prunable

prunable means the directory is gone. Clear the record:

git worktree prune
git branch -d feature/auth

Check what prune will remove first if you want to be careful:

git worktree prune --dry-run -v
Removing worktrees/myrepo-auth: gitdir file points to non-existent location

Case 3: the worktree is somewhere else entirely

If the path is on an unmounted drive or a machine share, git may be right to hold on. Mount it, then remove properly. If the worktree was locked (git worktree lock), prune deliberately skips it:

git worktree unlock ../myrepo-usb
git worktree remove ../myrepo-usb
git branch -d feature/auth

The same rule shows up from the other direction when you try to check out a branch a worktree already holds:

fatal: 'feature/auth' is already checked out at '/Users/you/code/myrepo-auth'

Same cause, same fixes. git worktree add gives you the identical message when the branch is spoken for.

The one-liner

If you already know the folder is gone and the branch is merged:

git worktree prune && git branch -d feature/auth

Avoiding it next time

The error only appears because a worktree outlived its usefulness without being removed. Delete worktrees with git worktree remove, not with rm -rf, and prune when you slip. Details in how to remove a git worktree and a worktree workflow that stays tidy.

Running parallel agent sessions makes this error much more frequent, because worktrees get created and abandoned faster than anyone cleans up. crystl closes that loop: isolated sessions own their worktree, and closing one asks whether to merge, keep, or discard, so stale claims don’t pile up.

Next