This Git error occurs when you try to checkout a branch that doesn't exist locally or hasn't been fetched from the remote repository. The error indicates Git cannot find any branch, file, or reference matching what you specified. Fix it by fetching remote branches first or verifying the branch name.
This error occurs when you run `git checkout <branch-name>` or `git switch <branch-name>`, but Git cannot find any branch, file, or reference matching the name you provided. Git treats branch names and file paths similarly in checkout commands, so "pathspec" refers to either. The most common scenario is trying to checkout a remote branch that exists on GitHub, GitLab, or another remote, but hasn't been fetched to your local repository yet. Your local Git only knows about branches it has downloaded references for. This can also happen if: - You mistyped the branch name - The branch was deleted from the remote - Your repository was cloned with limited fetch settings (e.g., shallow clone or single-branch clone) - There are multiple remotes and Git cannot determine which one to use
The most common fix is to fetch the latest branch information from the remote:
# Fetch all branches and tags from all remotes
git fetch --all
# Now try checking out the branch again
git checkout feature-branchIf you only want to fetch from a specific remote:
git fetch originAfter fetching, Git will have the remote tracking branches available.
Double-check that the branch name is correct and exists:
# List all local branches
git branch
# List all remote branches
git branch -r
# List ALL branches (local and remote)
git branch -a
# Search for a specific branch pattern
git branch -a | grep -i featureBranch names are case-sensitive on most systems. Make sure you're using the exact name shown in git branch -a.
Check on GitHub/GitLab:
If the branch should exist but doesn't appear, verify it on the remote's web interface. It may have been deleted or renamed.
If simple checkout fails, explicitly create a local branch that tracks the remote:
# Method 1: checkout with explicit tracking
git checkout -b feature-branch origin/feature-branch
# Method 2: Using --track flag
git checkout --track origin/feature-branch
# Method 3: Using git switch (Git 2.23+)
git switch --track origin/feature-branchThis creates a new local branch feature-branch that tracks origin/feature-branch.
If your repository was cloned with --single-branch or has restricted fetch settings, update the configuration:
# Check current fetch configuration
git config --get remote.origin.fetch
# If it shows something like +refs/heads/main:refs/remotes/origin/main
# Change it to fetch all branches:
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
# Now fetch all branches
git fetch origin
# Try checkout again
git checkout feature-branchThis is common in CI/CD environments or shallow clones.
When you have multiple remotes (e.g., origin and upstream), Git may not automatically determine which remote's branch to track:
# List all remotes
git remote -v
# See which remote has the branch
git branch -r | grep feature-branch
# Output might show:
# origin/feature-branch
# upstream/feature-branch
# Explicitly specify which remote to track
git checkout -b feature-branch origin/feature-branch
# Or
git checkout -b feature-branch upstream/feature-branchIf the same branch name exists on multiple remotes, you must be explicit about which one to use.
Sometimes local references become stale. Update them:
# Update remote refs and remove deleted branches
git remote update --prune
# Or using fetch with prune
git fetch --prune
# List branches again
git branch -aThe --prune flag removes local references to branches that no longer exist on the remote. This can also reveal if a branch was deleted.
If you cloned with --depth, you may need to fetch the full history:
# Check if this is a shallow clone
git rev-parse --is-shallow-repository
# If true, unshallow the repository
git fetch --unshallow
# Now fetch all branches
git fetch --all
# Try checkout again
git checkout feature-branchShallow clones are common in CI/CD to save time, but they limit access to full branch history.
### Understanding Git's Branch Resolution
When you run git checkout branch-name, Git searches for matches in this order:
1. Local branches in .git/refs/heads/
2. Remote tracking branches in .git/refs/remotes/
3. Tags in .git/refs/tags/
4. Files or directories in the working tree
If multiple matches exist (e.g., same name on multiple remotes), Git cannot automatically choose and requires explicit specification.
### The checkout.guess Configuration
Git 2.30+ introduced a configuration option that affects automatic remote branch guessing:
# Check current setting
git config checkout.guess
# If set to false, Git won't guess remote branches
# Enable guessing (default behavior)
git config checkout.guess true### Difference Between git checkout and git switch
Git 2.23 introduced git switch as a clearer alternative to checkout for branch operations:
| Command | Purpose |
|---------|---------|
| git switch branch | Switch branches only |
| git checkout branch | Switch branches OR restore files |
| git restore file | Restore files only |
Using git switch avoids ambiguity between branches and files.
### Why "pathspec" in the Error?
The term "pathspec" comes from Git's unified handling of paths. A "pathspec" can refer to:
- A branch name (feature-branch)
- A file path (src/index.ts)
- A pattern (*.js)
When Git can't find what you're looking for, it uses this generic term because it doesn't know if you meant a branch or a file.
### CI/CD Considerations
Many CI/CD systems clone repositories with limited history or single branches for performance. If your pipeline needs to checkout different branches:
# GitHub Actions example
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Fetch all history
# GitLab CI example
variables:
GIT_DEPTH: 0 # Disable shallow cloning### Debugging Branch Visibility
# Show detailed remote information
git remote show origin
# List all refs (including those not shown by git branch)
git for-each-ref --format='%(refname)' refs/
# Check if a specific ref exists
git show-ref refs/remotes/origin/feature-branchwarning: BOM detected in file, this may cause issues
UTF-8 Byte Order Mark (BOM) detected in file
fatal: Server does not support --shallow-exclude
Server does not support --shallow-exclude
warning: filtering out blobs larger than limit
Git partial clone filtering large blobs warning
fatal: Server does not support --shallow-since
Server does not support --shallow-since in Git
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server