Git · troubleshooting

error: pathspec did not match any file(s) known to git

git checkout did not find a local branch, tag or file with that name, so it treated the name as a file path and matched nothing. Usually the branch exists only on the remote and has not been fetched yet, or the name is misspelled; git fetch, then check it out again.

Reproduced on Git 2.50.1, 22 Oct 2026. Where the text says “reproduced”, the behaviour was run on that version, not taken from documentation.

First published 22 Oct 2026

New to this? Read what is actually happening first, then come back to the steps.

On this page · 8 sections

Before you start

A terminal in the repository, and access to the remote.

Run this first

step 1 of 2

git branch -a

Look for Whether the branch appears at all, locally or under remotes/origin/

Lists local branches and the remote-tracking ones your clone knows about.

Work out which cause you have

A few questions to narrow the list. Every answer ends in a command that confirms or rules the cause out — this cannot see your cluster, so nothing here is a certainty until you have checked.

Narrow it down

0 answered · nothing is sent anywhere

Does git ls-remote --heads origin list the branch?

Cause space

2 of 2 still possible

The branch exists only on the remote and is not fetchedCommon
The name is misspelled or the branch does not existCommon

Nothing ruled out yet. Answer the question above and the branches your answer eliminates will strike through here.

Or diagnose it manually

In this order. The first command usually contains the whole answer.

Step 1
```
git branch -a
```
Lists local branches and the remote-tracking ones your clone knows about.
Look for Whether the branch appears at all, locally or under remotes/origin/
Step 2
```
git ls-remote --heads origin
```
Asks the remote directly which branches exist, without fetching.
Look for The branch name

Every cause, and how to fix it

Ordered by how often each one turns out to be the answer.

The branch exists only on the remote and is not fetched

Common

Someone pushed the branch after your last fetch (or your clone is shallow or single-branch), so your repository has no record of it.

Confirm

git branch -a | grep NAME
git ls-remote --heads origin NAME

Nothing locally, but a line from ls-remote (the branch exists on the remote)

Fix

Fetch, then check it out: git fetch origin, then git checkout NAME (or git switch NAME).
For a single-branch or shallow clone: git fetch origin NAME:NAME, or git remote set-branches origin '*' followed by git fetch.

git fetch origin && git checkout NAME

Reproduced on Git 2.50.1: creates a local branch tracking origin/NAME.

The name is misspelled or the branch does not exist

Common

A typo, different case, a missing prefix such as feature/, or a branch that was deleted.

Confirm

git branch -a

The exact branch name, compared character by character

Fix

Use the exact name from git branch -a (without the remotes/origin/ prefix).

Understanding it properly

Skip this if you are mid-incident — the working part of the page is above. Worth reading afterwards, because understanding the mechanism is what stops the next one.

In plain terms

git checkout NAME first looks for a branch or tag called NAME, then for a file. If neither exists locally, it reports that the 'pathspec' (the name you gave) matched nothing. Branches other people pushed only become known to your clone after you fetch, so a branch you can see on GitHub can still be unknown locally.

Words used on this page

Pathspec: What Git calls a name or pattern given on the command line; checkout tries it as a branch first, then as a file path.
Remote-tracking branch: Your clone's copy of a branch on the remote, such as origin/feature/login. It only updates when you fetch.

What is actually happeningadvanced

Reproduced on Git 2.50.1: in a clone made before feature/login was pushed, git checkout feature/login printed error: pathspec 'feature/login' did not match any file(s) known to git and exited 1. After git fetch origin, the same command created the branch and set it to track origin/feature/login.

A misspelled branch name gives exactly the same error, so check the name against git branch -a.

Other commands word it differently: git add of a missing file says fatal: pathspec 'NAME' did not match any files, and git switch NAME says fatal: invalid reference: NAME.

In CI, a shallow or single-branch checkout often fetches only one branch, so other branches are unknown until fetched explicitly.

How to tell this is your problemsignals

Where	What you see
git checkout	error: pathspec 'BRANCH' did not match any file(s) known to git
git switch	fatal: invalid reference: BRANCH
git add	fatal: pathspec 'FILE' did not match any files

How to know it is actually fixed

git checkout NAME prints Switched to a new branch 'NAME' and that it tracks origin/NAME.

Stopping it happening again

Run git fetch before checking out branches other people created.
In CI, fetch the branches a job needs explicitly instead of relying on a single-branch checkout.

Sources

Behaviour described here is drawn from official documentation. Where a figure could not be confirmed on an official page it is attributed in the text rather than stated as canonical.

Did this get you to an answer?

No text box on purpose — please do not paste production logs anywhere

Something wrong or out of date? Report it