How to fix npm ERR! code EPREPAREGIT npm ERR! Could not checkout git ref for dependency in npm

npmINTERMEDIATEMEDIUMUpdated Dec 5, 2025· 116 views

This error occurs when npm cannot find the specified Git branch, tag, or commit for a Git-based dependency. The reference you're trying to install doesn't exist in the repository, or npm can't access it.

Quick fix

Fixes npm ERR! code EPREPAREGIT npm ERR! Could not checkout git ref for dependency

git ls-remote https://github.com/user/repo.git
  1. Verify the Git reference exists in the remote repository
  2. Update package.json with the correct Git reference
  3. Clear npm cache and delete lockfiles
  4. Reinstall dependencies and check for authentication issues
npm — error
git ls-remote https://github.com/user/repo.git
npm ERR! code EPREPAREGIT
npm ERR! Could not checkout git ref for dependency

What this error means

The EPREPAREGIT error happens during the preparation phase of installing a Git-based dependency. When you specify a Git URL in package.json with a reference (like `git+https://github.com/user/repo.git#branch-name`), npm attempts to clone the repository and checkout the exact reference you specified. If that reference (branch, tag, or commit SHA) doesn't exist or isn't accessible, npm fails with EPREPAREGIT. The error typically means one of three things: (1) the reference doesn't exist in the repository, (2) npm can't authenticate to access a private repository, or (3) network connectivity is preventing npm from reaching the Git server.

Typical symptoms

  • npm install fails with 'npm ERR! code EPREPAREGIT' message
  • Error mentions 'Could not checkout' followed by a branch name, tag, or commit SHA
  • Other dependencies install fine, but only Git-based dependencies fail
  • Error persists even after trying npm install again
  • Private Git repositories fail while public ones may work

Common causes

  1. The branch, tag, or commit specified in package.json doesn't exist in the remote repository
  2. The Git reference exists but was misspelled in package.json - for example, using 'master' when the default branch is 'main'
  3. Authentication failure on private repositories - SSH keys aren't configured or tokens expired
  4. Outdated or corrupted npm cache storing stale information about the Git repository
  5. Network or firewall issues preventing access to the Git server

How to fix "npm ERR! code EPREPAREGIT npm ERR! Could not checkout git ref for dependency"

1Verify the Git reference exists in the remote repository

Before anything else, confirm that the branch, tag, or commit you're trying to use actually exists. Use git ls-remote to check:

bash
git ls-remote https://github.com/user/repo.git

This will list all branches, tags, and refs available. Look for the exact reference you specified in package.json. Common mistakes:
- Using 'master' when the default branch is 'main'
- Missing the 'v' prefix on tags (e.g., using '1.0.0' instead of 'v1.0.0')
- Referencing a branch that was deleted or renamed

2Update package.json with the correct Git reference

Once you've confirmed the correct reference exists, update your package.json with the exact name:

json
{
  "dependencies": {
    "my-package": "git+https://github.com/user/repo.git#main",
    "private-package": "git+ssh://git@github.com:user/private-repo.git#v2.1.0"
  }
}

Note the syntax:
- git+https:// for HTTPS URLs
- git+ssh:// for SSH URLs
- #branch-name, #tag-name, or #commit-sha for the reference

3Clear npm cache and delete lockfiles

npm caches Git repositories, and stale cache can cause issues. Clear it forcefully:

bash
npm cache clean --force

Then delete your local dependency files:

bash
rm -rf node_modules package-lock.json

This ensures npm will fetch fresh data from the remote repository instead of using cached information.

4Reinstall dependencies and check for authentication issues

Now install fresh:

bash
npm install

If you're working with private repositories and still see EPREPAREGIT, you likely have an authentication issue. Test your Git access:

bash
ssh -T git@github.com

For HTTPS with GitHub, you may need to use a Personal Access Token (PAT) instead of your password.

5Try HTTPS instead of SSH if issues persist

Sometimes one protocol works better than the other. If you were using SSH and it failed, try HTTPS:

json
{
  "dependencies": {
    "my-package": "git+https://github.com/user/repo.git#branch"
  }
}

You can also configure git globally to prefer one protocol:

bash
git config --global url."https://github.com/".insteadOf git@github.com:

Advanced notes

For organizations using GitHub: ensure your personal access token has the correct scopes (repo, read:packages). For self-hosted Git servers behind firewalls, you may need to configure an HTTP proxy. If you need semantic versioning with Git dependencies, use the special semver: prefix in the reference: git+https://github.com/user/repo.git#semver:^1.0.0 - npm will search tags matching that version range.

Frequently asked questions

What does "npm ERR! code EPREPAREGIT npm ERR! Could not checkout git ref for depe" mean?
The EPREPAREGIT error happens during the preparation phase of installing a Git-based dependency. git#branch-name), npm attempts to clone the repository and checkout the exact reference you specified. If that reference (branch, tag, or commit SHA) doesn't exist or isn't accessible, npm fails with EPREPAREGIT.
How do I fix "npm ERR! code EPREPAREGIT npm ERR! Could not checkout git ref for depe"?
This error occurs when npm cannot find the specified Git branch, tag, or commit for a Git-based dependency. The reference you're trying to install doesn't exist in the repository, or npm can't access it.
What causes "npm ERR! code EPREPAREGIT npm ERR! Could not checkout git ref for depe"?
The branch, tag, or commit specified in package.json doesn't exist in the remote repository The Git reference exists but was misspelled in package.json - for example, using 'master' when the default branch is 'main' Authentication failure on private repositories - SSH keys aren't configured or tokens expired
Is the "npm ERR! code EPREPAREGIT npm ERR! Could not checkout git ref for depe" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading