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.
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.
Check the repository to confirm the reference exists:
# 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/tagsLook for the exact name you're referencing in your package.json.
Update the dependency to use a valid reference:
{
"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
For more reliable installations, use a specific commit hash instead of a branch name:
{
"dependencies": {
"my-package": "github:user/repo#a1b2c3d4e5f6"
}
}This ensures the dependency won't break if branches are renamed or deleted.
After fixing package.json, clean your installation:
rm -rf node_modules package-lock.json
npm installGit 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://[email protected]: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://[email protected]/user/repo.git#ref
npm notice access token expired or revoked. Please try logging in again.
Token has expired - npm authentication failure
npm ERR! code EAI_AGAIN
How to fix "EAI_AGAIN" in npm
npm error code E403 npm error 403 Forbidden - PUT https://registry.npmjs.org/<package>
How to fix 'E403 Forbidden' error in npm
npm ERR! code EUSAGE npm ERR! Usage error
How to fix "npm ERR! code EUSAGE" in Node.js projects
npm ERR! code E401 npm ERR! 401 Unauthorized
How to fix "E401 Unauthorized" in npm