Fixing 'fatal: Cannot delete branch … checked out at …' in Git

Overview

This error happens when you try to delete a local branch that is currently checked out in your main working directory or in another linked worktree. Git prevents deletion to avoid corrupting a checked-out branch.

Typical message:

• fatal: Cannot delete branch 'feature' checked out at '/path/to/worktree'

Quickstart

• Identify where the branch is checked out: git worktree list
• If it’s your current repo: git switch <another-branch>
• If it’s in another worktree: switch there or remove that worktree
• Delete the branch: git branch -d <branch> (or -D if unmerged and you’re sure)

Minimal working example

This reproduces the error and shows two fixes.

# Start clean
mkdir demo && cd demo

git init

echo one > file.txt
git add file.txt
git commit -m "init"

git branch feature

# Create a linked worktree that checks out the 'feature' branch
git worktree add ../wt-feature feature

# Attempt to delete 'feature' from the main repo (will fail)
git branch -d feature
# fatal: Cannot delete branch 'feature' checked out at '/absolute/path/../wt-feature'

# Fix A: switch the worktree away from 'feature'
git -C ../wt-feature switch main
# Now delete the branch
git branch -d feature

# Alternative Fix B: remove the worktree (destroys that working dir)
# Only do this if you don't need that directory anymore
# (commits remain in the repo; uncommitted changes will be lost)
# Reset the scenario first so feature exists again:
git branch feature
git worktree add ../wt-feature feature

git worktree remove ../wt-feature --force
# Now delete the branch
git branch -d feature

Why this happens

• A branch cannot be deleted if it is the current HEAD of any worktree attached to the repository.
• This includes your primary working directory and any linked worktrees created via git worktree add.

Step-by-step resolution

1. Find where the branch is checked out

git worktree list --porcelain

Look for the worktree path whose branch matches the branch you’re trying to delete.

1. If the branch is checked out in your current repo

git switch <another-branch>
# or
git checkout <another-branch>

Then delete it:

git branch -d <branch>
# or (force if needed)
git branch -D <branch>

1. If the branch is checked out in another linked worktree

Option A: Switch that worktree to another branch (non-destructive):

git -C /path/to/worktree switch <another-branch>

Then delete the branch from your main repo:

git branch -d <branch>

Option B: Remove the linked worktree (destructive to that directory):

git worktree remove /path/to/worktree --force

Then delete the branch:

git branch -d <branch>

1. Clean up stale metadata (optional)

If the path in the error no longer exists (e.g., you deleted it manually), prune the stale entry:

git worktree prune

Try deleting the branch again.

1. If you also need to remove the remote branch (optional)

Deleting a local branch does not remove the remote branch.

git push origin --delete <branch>
# Or for older servers: git push origin :<branch>

Update local refs:

git fetch --prune

Common scenarios and commands

Pitfalls

• Forcing deletion with -D bypasses the “unmerged commits” check but does not bypass the “checked out” protection. You still must switch or remove the worktree.
• Removing a worktree with git worktree remove --force deletes that working directory. Uncommitted changes in that directory are lost.
• GUI tools or IDEs may keep a worktree on a branch. Close the project or switch branches in the IDE before deleting.
• Don’t confuse local and remote branches. Deleting local refs doesn’t affect the remote until you push the deletion.
• If the error references a path that no longer exists, use git worktree prune to clean stale references before retrying.

Performance notes

• git worktree list --porcelain is fast and scales linearly with the number of worktrees. Prefer it over shelling into each directory.
• Using git -C <path> avoids cd and can be scripted efficiently to switch branches across multiple worktrees.
• Deleting a branch is O(1) metadata work; the heavy operations are typically in your CI or remote operations (e.g., git push).
• Pruning stale worktrees is cheap and helps keep operations like tab completion and tooling snappy in large repos.

Tiny FAQ

Q: Why does git branch -D <branch> still fail? A: -D only overrides the “not fully merged” check. Git still forbids deleting a branch that is checked out anywhere.

Q: How do I find which worktree has the branch? A: Run git worktree list --porcelain and look for the matching branch entry and its path.

Q: Is it safe to remove a worktree? A: It removes the directory. Commits remain in the repo, but uncommitted changes in that worktree are lost.

Q: Do I need to delete the remote branch too? A: Only if you intend to remove it from the server. Use git push origin --delete <branch>.

Q: Can I automate cleanup? A: Yes. Script: list worktrees, switch each away from target branch, remove any that are disposable, prune, then delete the branch.