tools-only Worktree Troubleshooting (Agent Reference)
Common errors
"not a git repository"
- You are not in
main/. Change to the repo root and retry.
- You are not in
"fatal: A branch named 'X' already exists"
- Use
git worktree add <path> <branch>without-b.
- Use
"worktree already exists" / path exists
- Pick a new directory name or remove the old worktree:
git worktree remove <path>
- Pick a new directory name or remove the old worktree:
"locked" worktree
- Run
git worktree pruneand retry.
- Run
Uncommitted changes block checkout
- Commit, stash, or clean the working tree before creating a new worktree.
Clean up
git worktree list
git worktree prune