Introduction

The error error: pathspec 'branch-name' did not match any file(s) known to git means Git cannot find a branch, tag, or file matching the name you provided. This almost always falls into one of four causes: a typo, a missing git fetch, a remote-only branch that needs explicit tracking, or a case-sensitivity mismatch. Here is how to diagnose and fix each one.

Understanding What the Error Means

When you run git checkout branch-name (or git switch branch-name), Git searches in this order:

1. Local branches
2. Remote-tracking branches (to auto-create a local tracking branch)
3. Tags
4. Files or paths in the working tree

If nothing matches, Git reports the pathspec error. The message says "file(s)" because git checkout historically handled both branch switching and file restoration.

Cause 1: The Branch Has Not Been Fetched

This is the most common cause, especially in team environments. A colleague created a branch, pushed it, and you try to check it out. But your local repository does not know about it yet.

Fix:

1# Fetch all branches from all remotes
2git fetch --all
3
4# Now try again
5git checkout feature/user-auth

If you only want to fetch from a specific remote:

git fetch origin
git checkout feature/user-auth

Verifying the Branch Exists on the Remote

1# List all remote-tracking branches
2git branch -r
3
4# Search for a specific branch
5git branch -r | grep user-auth

If the branch does not appear in git branch -r even after fetching, it either does not exist on the remote or was deleted.

Cause 2: Typo or Case Mismatch

Git branch names are case-sensitive. Feature/Login, feature/login, and feature/Login are three different branches.

Fix:

1# List all branches (local and remote) to find the exact name
2git branch -a
3
4# Example output:
5#   main
6#   remotes/origin/main
7#   remotes/origin/feature/Login    <-- note the capital L

Then use the exact name:

git checkout feature/Login

Using Tab Completion

Most shells support tab completion for Git branch names. Type git checkout feat and press Tab to see matching branches. This avoids typos entirely.

Cause 3: Remote-Only Branch with Multiple Remotes

When you have multiple remotes (e.g., origin and upstream), Git's automatic tracking branch creation can fail because it does not know which remote to use.

Fix:

1# Explicitly specify the remote
2git checkout -b feature/payment origin/feature/payment
3
4# Or with git switch (Git 2.23+)
5git switch -c feature/payment origin/feature/payment

This creates a local branch feature/payment that tracks origin/feature/payment.

Cause 4: Shallow Clone Missing the Branch

If you cloned with --depth 1 or --single-branch, your repository may not have all branch references.

Fix:

1# Unshallow the clone
2git fetch --unshallow
3
4# Or fetch a specific branch from a single-branch clone
5git remote set-branches --add origin feature/payment
6git fetch origin
7git checkout feature/payment

Cause 5: Branch Was Deleted

The branch may have existed at one point but was deleted from the remote (e.g., after a pull request was merged).

Verify:

# Prune stale remote-tracking references and check
git fetch --prune
git branch -r | grep branch-name

If the branch no longer appears, it was deleted. You can check with the hosting platform (GitHub, GitLab) whether the branch still exists.

Diagnostic Flowchart

Follow these steps in order to resolve the error:

11. git fetch --all
22. git branch -a | grep <name>
3   Found? --> git checkout <exact-name>
4   Not found? --> Continue
53. git branch -r | grep -i <name>    (case-insensitive search)
6   Found with different case? --> git checkout <correct-case-name>
7   Not found? --> Continue
84. Check if the clone is shallow: git rev-parse --is-shallow-repository
9   true? --> git fetch --unshallow, then retry
105. Branch was deleted or never existed.

git checkout vs git switch

Since Git 2.23 (August 2019), the recommended command for switching branches is git switch, which separates branch-switching from file-restoration:

The error message is the same with git switch, but using the newer commands makes intent clearer and avoids accidental file overwrites.

Common Pitfalls

• Running git checkout before git fetch. Your local repository only knows about remote branches after fetching. Always fetch first.
• Copy-pasting branch names from Slack or Jira. Chat tools and project trackers sometimes convert hyphens, add invisible Unicode characters, or change capitalization. Type the branch name manually or use tab completion.
• Confusing origin/branch with branch. origin/feature-x is a remote-tracking reference, not a local branch. Running git checkout origin/feature-x puts you in a detached HEAD state. Instead, run git checkout feature-x (without the origin/ prefix) to create a local tracking branch.
• Stale remote-tracking references. If a branch was renamed or deleted on the remote, your local git branch -r output may still show the old name. Run git fetch --prune to clean up.
• NTFS or FAT32 case-insensitivity. On Windows, the filesystem is case-insensitive, which can cause Git to conflate branches like feature/API and feature/api. Stick to lowercase branch names on Windows.

Summary

• The pathspec error means Git cannot find a matching branch, tag, or file.
• Run git fetch --all first. This fixes the problem in most cases.
• Use git branch -a to list all branches and verify the exact name (including case).
• For multiple remotes, explicitly create a tracking branch with git checkout -b name origin/name.
• For shallow clones, run git fetch --unshallow to retrieve all branch references.
• Prefer git switch over git checkout for branch switching to avoid ambiguity between branches and files.