How to fix npm ERR! git checkout failed npm ERR! error: pathspec 'branch-name' did not match any file(s) known to git in npm

npmBEGINNERMEDIUMUpdated Dec 5, 2025· 133 views

This error occurs when npm tries to install a Git dependency but cannot find the specified branch, tag, or commit. Usually caused by a typo in the reference name, a deleted branch, or using semver syntax on Git URLs.

Quick fix

Fixes npm ERR! git checkout failed npm ERR! error: pathspec 'branch-name' did not match any file(s) known to git

# List all remote branches and tags
git ls-remote https://github.com/user/repo.git

# Or visit the repository on GitHub/GitLab and check branches/tags

Verify the branch or tag exists
Fix the reference in package.json
Use a commit SHA for stability
Clean and reinstall

npm — error

$# List all remote branches and tags
git ls-remote https://github.com/user/repo.git
# Or visit the repository on GitHub/GitLab and check branches/tags
npm ERR! git checkout failed
npm ERR! error: pathspec 'branch-name' did not match any file(s) known to git

What this error means

When you specify a Git dependency in your package.json with a branch, tag, or commit reference (like `github:user/repo#feature-branch`), npm clones the repository and tries to checkout that reference. This error means the reference doesn't exist in the repository. Unlike regular npm packages that support semver ranges (`^1.0.0`, `~2.3.0`), Git dependencies require exact references. You can't use `#^1.0.0` on a Git URL—you must use the actual tag name, branch name, or commit SHA that exists in the repository. This is one of the most common issues when working with Git dependencies, especially when the upstream repository has been updated and the referenced branch or tag no longer exists.

Typical symptoms

npm install fails with 'pathspec did not match any file(s) known to git'
Error shows the specific branch or tag name that couldn't be found
Only affects Git dependencies, not regular npm registry packages
Error includes 'npm ERR! git checkout failed'

Common causes

Typo in branch or tag name in package.json (e.g., 'mian' instead of 'main')
Referenced branch was deleted or renamed in the upstream repository
Using semver syntax (^1.0.0) instead of actual tag name on Git URL
Tag exists but with different format (e.g., 'v1.0.0' vs '1.0.0')
Private repository requires authentication to list branches

How to fix "npm ERR! git checkout failed npm ERR! error: pathspec 'branch-name' did not match any file(s) known to git"

1Verify the branch or tag exists

Check the repository to confirm the reference exists:

bash

# List all remote branches and tags
git ls-remote https://github.com/user/repo.git

# Or visit the repository on GitHub/GitLab and check branches/tags

Look for the exact name you're referencing in your package.json.

2Fix the reference in package.json

Update the dependency to use a valid reference:

json

{
  "dependencies": {
    // Before (broken - branch doesn't exist)
    "my-package": "github:user/repo#invalid-branch",

    // After (fixed - use existing branch or tag)
    "my-package": "github:user/repo#main"
  }
}

Common reference formats:
- github:user/repo#branch-name - specific branch
- github:user/repo#v1.0.0 - specific tag
- github:user/repo#abc123 - specific commit SHA

3Use a commit SHA for stability

For more reliable installations, use a specific commit hash instead of a branch name:

json

{
  "dependencies": {
    "my-package": "github:user/repo#a1b2c3d4e5f6"
  }
}

This ensures the dependency won't break if branches are renamed or deleted.

4Clean and reinstall

After fixing package.json, clean your installation:

bash

rm -rf node_modules package-lock.json
npm install

Advanced notes

Git URL Syntax: npm supports several Git URL formats:
- git://github.com/user/repo.git#ref
- git+https://github.com/user/repo.git#ref
- git+ssh://git@github.com:user/repo.git#ref
- github:user/repo#ref (shorthand)

Default Reference: If you omit the #ref part, npm defaults to the repository's default branch (usually main or master).

No Semver Ranges: Git dependencies don't support semver ranges. github:user/repo#^1.0.0 will fail—you must use github:user/repo#v1.0.0 (the actual tag name).

Private Repositories: If the repository is private, ensure you have SSH keys configured or use HTTPS with a token: git+https://TOKEN@github.com/user/repo.git#ref

Frequently asked questions

What does "npm ERR! git checkout failed npm ERR! error: pathspec 'branch-name' di" mean?: json with a branch, tag, or commit reference (like github:user/repo#feature-branch), npm clones the repository and tries to checkout that reference. This error means the reference doesn't exist in the repository. 0), Git dependencies require exact references.
How do I fix "npm ERR! git checkout failed npm ERR! error: pathspec 'branch-name' di"?: This error occurs when npm tries to install a Git dependency but cannot find the specified branch, tag, or commit. Usually caused by a typo in the reference name, a deleted branch, or using semver syntax on Git URLs.
What causes "npm ERR! git checkout failed npm ERR! error: pathspec 'branch-name' di"?: Typo in branch or tag name in package.json (e.g., 'mian' instead of 'main') Referenced branch was deleted or renamed in the upstream repository Using semver syntax (^1.0.0) instead of actual tag name on Git URL
Is the "npm ERR! git checkout failed npm ERR! error: pathspec 'branch-name' di" error serious?: It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚npm Official Documentation
📖
Docs: Git URLs as dependencies(Official Docs)
💬
SO: git checkout failed(Stack Overflow)
🐙
GitHub: npm git resolution issues(GitHub)