How to fix fatal: invalid reference: branch-name in Git

What this error means

This error occurs when Git cannot locate the reference (branch, tag, or commit) you're trying to check out. In Git terminology, a "reference" is any pointer to a commit - most commonly a branch name. When you see "fatal: invalid reference: branch-name", Git is telling you that it searched its list of local branches, remote tracking branches, tags, and other refs, but couldn't find anything matching that name. About 90% of the time, this error simply means "this branch doesn't exist." The reference could be misspelled, using incorrect casing (Git is case-sensitive), or the remote branch may not have been fetched to your local repository yet. This is one of the most common Git errors, especially when working with multiple remotes, switching between repositories, or trying to check out branches from remote repositories without fetching first.

Typical symptoms

• git checkout command fails with 'fatal: invalid reference'
• git switch command reports the branch doesn't exist
• Unable to check out a branch that exists on the remote
• Branch name appears correct but Git still reports it as invalid
• Error occurs when using branch names with special characters or spaces
• CI/CD pipeline fails when checking out specific branches
• Tab completion for branch names doesn't show the expected branch
• git branch -a doesn't list the expected remote branch

Common causes

1. Typo in the branch name (most common cause)
2. Case mismatch - Git branch names are case-sensitive
3. Remote branch not fetched - the branch exists on the server but not locally
4. Branch was deleted on the remote but local refs weren't updated
5. Invalid characters in the branch name (spaces, special chars)
6. Branch name conflicts with shell interpretation (brackets, asterisks)
7. Stale remote-tracking references after repository history rewrite
8. Branch name starts with a hyphen or is named 'HEAD' (reserved)

How to fix "fatal: invalid reference: branch-name"

# List all local branches
git branch

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

# List branches with more details
git branch -vv

# Fetch all branches from all remotes
git fetch --all

# Fetch from a specific remote
git fetch origin

# Fetch and prune deleted remote branches
git fetch --prune

git branch -a | grep branch-name

# Checkout and track the remote branch
git checkout branch-name

# Or explicitly create a local branch tracking the remote
git checkout -b branch-name origin/branch-name

# These are different branches in Git:
git checkout feature-branch    # lowercase
git checkout Feature-Branch    # mixed case
git checkout FEATURE-BRANCH    # uppercase

# Case-insensitive search for branches
git branch -a | grep -i "branch-name"

# Show all references containing the name
git show-ref | grep -i "branch-name"

# Branch names with brackets need quoting (especially in zsh)
git checkout "feature/[JIRA-123]"

# Branch names with spaces (not recommended but possible)
git checkout "feature with spaces"

# Use single quotes to prevent variable expansion
git checkout 'feature/$variable'

# Check if the reference exists
git show-ref --verify --quiet refs/heads/branch-name && echo "Branch exists" || echo "Branch not found"

# Check for remote branches
git show-ref --verify --quiet refs/remotes/origin/branch-name && echo "Remote branch exists" || echo "Not found"

# List all references to find the correct name
git show-ref

# Create a new branch at current HEAD
git checkout -b branch-name

# Create a new branch from a specific commit
git checkout -b branch-name commit-hash

# Create a branch tracking a remote branch
git checkout -b branch-name origin/branch-name

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

# Or prune a specific remote
git remote prune origin

# Enable auto-pruning for future fetches
git config --global fetch.prune true

# Delete the local branch
git branch -d branch-name

# Force delete if it has unmerged changes
git branch -D branch-name

# Check repository for issues
git fsck

# Remove and re-add the remote
git remote remove origin
git remote add origin git@github.com:user/repo.git
git fetch origin

# Refresh all remote-tracking branches
git remote update origin --prune

# Move current repo and clone fresh
mv myrepo myrepo.backup
git clone git@github.com:user/repo.git
cd myrepo

# Copy any local uncommitted changes from backup if needed

Advanced notes

git check-ref-format --branch "proposed-name"

# Switch to existing branch
git switch branch-name

# Create and switch to new branch
git switch -c new-branch

# Create branch tracking remote
git switch -c branch-name --track origin/branch-name

# Create a branch at current detached HEAD
git checkout -b new-branch-name

# Or return to a branch
git checkout main

# Fetch with full depth if shallow clone is causing issues
git fetch --unshallow

# Fetch specific branch explicitly
git fetch origin branch-name:refs/remotes/origin/branch-name

Frequently asked questions

What does "fatal: invalid reference: branch-name" mean?

This error occurs when Git cannot locate the reference (branch, tag, or commit) you're trying to check out. In Git terminology, a "reference" is any pointer to a commit - most commonly a branch name. When you see "fatal: invalid reference: branch-name", Git is telling you that it searched its list of local branches, remote tracking branches, tags, and other refs, but couldn't find anything matching that name.

How do I fix "fatal: invalid reference: branch-name"?

The 'fatal: invalid reference' error occurs when Git cannot find the branch, tag, or commit you specified. This typically happens due to typos, case sensitivity issues, or when the remote branch hasn't been fetched yet.

What causes "fatal: invalid reference: branch-name"?

Typo in the branch name (most common cause) Case mismatch - Git branch names are case-sensitive Remote branch not fetched - the branch exists on the server but not locally

Is the "fatal: invalid reference: branch-name" error serious?

It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• error: Your local changes to the following files would be overwritten by checkout

  How to fix 'Your local changes would be overwritten by checkout' in Git

  LOW

• error: pathspec 'branch-name' did not match any file(s) known to git

  How to fix "pathspec did not match any file(s) known to git" in Git

  LOW

• fatal: Cannot switch branch to a non-commit

  How to fix 'Cannot switch branch to a non-commit' in Git

  MEDIUM

• error: cannot rebase: You have unstaged changes. Please commit or stash them.

  How to fix 'cannot rebase: You have unstaged changes' in Git

  LOW

• API rate limit exceeded

  How to fix 'API rate limit exceeded' in GitHub

  MEDIUM

• fatal: destination path already exists and is not an empty directory

  Destination Path Already Exists and Is Not Empty

  LOW

Official resources & further reading

• 📚Git Official Documentation
• 📖
  Git Docs - git-checkout(Official Docs)
• 📖
  Git Docs - git-check-ref-format(Official Docs)
• 📖
  LabEx - How to resolve git checkout invalid reference(Official Docs)
• 💬
  Stack Overflow - Force argument to be interpreted as branch name(Stack Overflow)
• 📝
  Julia Evans - Notes on git's error messages