Fix: “fatal: invalid reference” in git worktree add

You try to create a new git worktree and get this error:

$ git worktree add ../feature-worktree feature/auth
fatal: invalid reference: feature/auth

This means Git cannot find the branch or commit you specified. Here is why it happens and how to fix it.

Why This Error Occurs

When you run git worktree add <path> <branch>, Git needs to resolve the branch name to an existing commit. The “invalid reference” error occurs when Git cannot do this. The most common reasons:

The branch does not exist locally. You may be trying to check out a remote branch that has not been fetched yet, or a branch that only exists on a remote like origin.
Typo in the branch name. Branch names are case-sensitive. Feature/auth is not the same as feature/auth.
The branch was deleted. Someone may have deleted the branch on the remote, or you may have deleted it locally.
You forgot the -b flag. If you want to create a new branch, you need -b. Without it, Git looks for an existing branch with that name.

Solutions

Solution 1: Fetch the Remote Branch First

If the branch exists on a remote but not locally, fetch it first:

# Fetch all branches from the remote
git fetch origin

# Now try again
git worktree add ../feature-worktree feature/auth

If the branch exists only on the remote and Git does not automatically create a local tracking branch, you can specify the remote ref directly:

# Create a worktree from a remote branch
git worktree add ../feature-worktree origin/feature/auth

# Or create a local tracking branch and check it out
git worktree add -b feature/auth ../feature-worktree origin/feature/auth

Solution 2: Use -b to Create a New Branch

If the branch does not exist yet and you want to create it, use the -b flag:

# Create a new branch AND a worktree for it in one step
git worktree add -b feature/auth ../feature-worktree

# This creates feature/auth based on HEAD (current commit)
# To base it on a different starting point:
git worktree add -b feature/auth ../feature-worktree origin/main

Solution 3: Check Your Spelling

List available branches to find the correct name:

# List local branches
git branch
#   main
# * develop
#   feature/authentication   <-- note: "authentication", not "auth"

# List remote branches
git branch -r
#   origin/main
#   origin/develop
#   origin/feature/authentication

# Search for a branch by partial name
git branch -a | grep -i auth
#   feature/authentication
#   remotes/origin/feature/authentication

Solution 4: Check If the Branch Was Deleted

If the branch was deleted on the remote, your local references may be stale:

# Prune stale remote-tracking branches
git fetch --prune origin

# See what branches actually exist now
git branch -r

Complete Examples

Working with a Remote Branch

# A colleague pushed a new branch. You want a worktree for it.

# Step 1: Fetch the latest refs
git fetch origin

# Step 2: Verify the branch exists
git branch -r | grep feature/auth
#   origin/feature/auth

# Step 3: Create the worktree
git worktree add ../auth-worktree feature/auth
# If that fails, try with the full remote ref:
git worktree add -b feature/auth ../auth-worktree origin/feature/auth

Creating a Brand-New Feature Branch

# You want to start a new feature in its own worktree
# Wrong (branch doesn't exist yet):
git worktree add ../new-feature feature/new-feature
# fatal: invalid reference: feature/new-feature

# Correct (use -b to create the branch):
git worktree add -b feature/new-feature ../new-feature

git worktree add — Full guide on creating worktrees
Fix: Branch already checked out — Another common worktree add error
All troubleshooting guides