How to fix fatal: invalid reference: feature in Git

GitINTERMEDIATELOWUpdated Dec 6, 2025· 248 views

This error occurs when git worktree add cannot find the branch or commit reference you specified. Common causes include the branch not existing locally, shallow clones, or typos in the branch name.

Quick fix

Fixes fatal: invalid reference: feature

# List all local branches
git branch

# List all branches including remote tracking branches
git branch -a

# Check if Git can resolve the reference
git rev-parse feature
  1. Verify the branch exists locally
  2. Fetch the branch from remote
  3. Create the worktree with a new tracking branch
  4. Use the full remote reference
git — error
# List all local branches
git branch
# List all branches including remote tracking branches
git branch -a
# Check if Git can resolve the reference
git rev-parse feature
fatal: invalid reference: feature

What this error means

When you run `git worktree add <path> <branch>`, Git tries to check out the specified branch into a new working tree directory. The "fatal: invalid reference" error means Git cannot resolve the branch name or commit reference you provided to an actual commit in your repository. Git worktrees allow you to have multiple working directories attached to a single repository, each checked out to a different branch. This is useful for working on multiple features simultaneously, running tests on one branch while coding on another, or comparing changes across branches without stashing. The reference Git is looking for must exist in your local repository. Unlike `git checkout`, which can automatically create a tracking branch from a remote, `git worktree add` requires the reference to already exist locally (unless you use the `-b` flag to create a new branch). This strict behavior catches many developers off guard, especially in CI/CD environments with shallow or single-branch clones.

Typical symptoms

  • Running git worktree add fails immediately with 'fatal: invalid reference: <branch>'
  • The error occurs even though you can see the branch on GitHub/GitLab
  • CI/CD pipelines (Jenkins, GitLab CI) fail when trying to create worktrees
  • The command works for some branches but not others
  • Running git branch -a shows the branch as origin/<branch> but worktree add still fails

Common causes

  1. The branch does not exist locally - only the remote tracking branch exists (most common)
  2. You have a shallow clone that doesn't include the branch's history
  3. Single-branch clone configured, so other branches weren't fetched
  4. Typo in the branch name or the branch was deleted
  5. Using a bare repository where HEAD points to the same branch you're trying to check out
  6. The branch name contains special characters or spaces that need escaping

How to fix "fatal: invalid reference: feature"

1Verify the branch exists locally

First, check what branches are available in your repository:

bash
# List all local branches
git branch

# List all branches including remote tracking branches
git branch -a

# Check if Git can resolve the reference
git rev-parse feature

If your branch only appears as remotes/origin/feature but not as a local branch, that's the problem - Git worktree needs a local reference.

2Fetch the branch from remote

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

bash
# Fetch all branches from origin
git fetch origin

# Or fetch a specific branch
git fetch origin feature:feature

The second command fetches the remote branch and creates a local branch with the same name.

For Jenkins/CI environments with shallow clones:

bash
# Configure fetch to get all branches
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"

# Fetch all branches
git fetch --all

# If you have a shallow clone, unshallow it
git fetch --unshallow
3Create the worktree with a new tracking branch

Use the -b flag to create a new local branch that tracks the remote:

bash
# Create worktree with a new branch tracking origin/feature
git worktree add -b feature ../feature-worktree origin/feature

# Or if you want the worktree directory named after the branch
git worktree add -b feature ./feature origin/feature

This creates a local branch feature that tracks origin/feature and checks it out into the specified directory.

4Use the full remote reference

If you just want to work with the remote branch without creating a local tracking branch, you can use --detach:

bash
# Create a worktree with detached HEAD at the remote branch
git worktree add --detach ../feature-worktree origin/feature

This creates a worktree in detached HEAD state pointing to the same commit as origin/feature. Note that any commits you make will not be on a branch until you create one.

5Handle shallow clones in CI/CD

Many CI systems use shallow clones for speed. To fix worktree issues in CI:

Jenkins:

groovy
// In Jenkinsfile
checkout([
    $class: 'GitSCM',
    branches: [[name: '*/main']],
    extensions: [[$class: 'CloneOption', shallow: false]],
    userRemoteConfigs: [[url: 'https://github.com/user/repo.git']]
])

GitLab CI:

yaml
# In .gitlab-ci.yml
variables:
  GIT_DEPTH: 0  # Disable shallow cloning
  GIT_STRATEGY: fetch

GitHub Actions:

yaml
# In workflow file
- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Fetch all history
6Clean up stale worktree references

If you previously had a worktree that was manually deleted (rm -rf instead of git worktree remove), Git may be confused:

bash
# List current worktrees
git worktree list

# Prune stale worktree information
git worktree prune

# Verify the worktree list is clean
git worktree list

After pruning, try creating the worktree again.

7Fix bare repository issues

In bare repositories, you cannot create a worktree for the branch that HEAD points to. Check your setup:

bash
# See what HEAD points to
git symbolic-ref HEAD

# If HEAD points to refs/heads/feature and you want a worktree for feature:
# Option 1: Change HEAD to a different branch first
git symbolic-ref HEAD refs/heads/main

# Option 2: Use a commit hash instead of branch name
git worktree add ../feature-worktree $(git rev-parse feature)
8Handle branch names with special characters

If your branch name contains spaces or special characters, quote it properly:

bash
# Branch with spaces (not recommended but possible)
git worktree add "../my worktree" "feature/my branch"

# Branch with slashes (common in Git Flow)
git worktree add ../hotfix-worktree feature/hotfix-123

If the error shows only part of your branch name (like "fatal: invalid reference: Library" when using a path with spaces), your path might be getting split. Always quote paths with spaces.

Advanced notes

### Understanding Git Worktree References

Git worktree is stricter about references than git checkout. Here's why:

1. No automatic DWIM (Do What I Mean): git checkout feature automatically creates a local branch tracking origin/feature if it exists. git worktree add does not - you must use -b explicitly.

2. FETCH_HEAD doesn't count: If you run git fetch origin feature, the commits are stored in FETCH_HEAD, not as a regular branch. The worktree command won't find them there.

3. Worktrees share the same .git: All worktrees share the same repository database. This means you cannot have the same branch checked out in multiple worktrees simultaneously (Git prevents this to avoid conflicts).

### The worktree.guessRemote Setting

You can make worktree behave more like checkout by enabling remote guessing:

bash
git config worktree.guessRemote true

With this setting, git worktree add ../feature feature will automatically look for origin/feature if feature doesn't exist locally.

### Worktree Lock for CI/CD

In CI environments where worktrees might be cleaned up unexpectedly:

bash
# Lock a worktree to prevent accidental pruning
git worktree lock ../feature-worktree --reason "CI build in progress"

# Unlock when done
git worktree unlock ../feature-worktree

### Repairing Broken Worktrees

If worktrees become disconnected (repository moved, paths changed):

bash
# Repair worktree links
git worktree repair

# Repair with explicit paths
git worktree repair ../old-path ../new-path

Frequently asked questions

What does "fatal: invalid reference: feature" mean?
When you run git worktree add <path> <branch>, Git tries to check out the specified branch into a new working tree directory. The "fatal: invalid reference" error means Git cannot resolve the branch name or commit reference you provided to an actual commit in your repository. Git worktrees allow you to have multiple working directories attached to a single repository, each checked out to a different branch.
How do I fix "fatal: invalid reference: feature"?
This error occurs when git worktree add cannot find the branch or commit reference you specified. Common causes include the branch not existing locally, shallow clones, or typos in the branch name.
What causes "fatal: invalid reference: feature"?
The branch does not exist locally - only the remote tracking branch exists (most common) You have a shallow clone that doesn't include the branch's history Single-branch clone configured, so other branches weren't fetched
Is the "fatal: invalid reference: feature" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading