npm fails to install dependencies from private Git repositories when it cannot authenticate with the remote server. This occurs when the system lacks valid credentials (SSH keys, personal access tokens, or cached credentials) to access the remote repository.
npm fails to install dependencies from private Git repositories when it cannot authenticate with the remote server. This occurs when npm invokes git clone to fetch packages specified in package.json, but the system lacks valid credentials (SSH keys, personal access tokens, or cached credentials). The error "fatal: Authentication failed" indicates Git received an invalid username/password combination, missing credentials, or misconfigured authentication method. npm does NOT directly handle authentication—it relies on Git's credential system. This means Git credential helpers must be configured, or SSH agent must be running for SSH URLs.
Test Git access directly to rule out network or permission issues:
# For SSH access
ssh -T [email protected]
# For HTTPS access
git clone https://github.com/owner/private-repo.gitIf SSH test fails with "Permission denied (publickey)", proceed to SSH setup.
If HTTPS test fails with authentication error, configure credentials.
Generate an SSH key and add it to your Git hosting service:
# Generate SSH key
ssh-keygen -t ed25519 -C "[email protected]"
# Start SSH agent and add key
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
# Display public key to copy to GitHub
cat ~/.ssh/id_ed25519.pubThen:
1. Go to GitHub Settings > SSH and GPG keys
2. Click "New SSH key" and paste the public key
3. Test: ssh -T [email protected]
Update package.json to use SSH URLs:
{
"dependencies": {
"private-package": "git+ssh://[email protected]:owner/repo.git"
}
}If using HTTPS authentication, create a token:
1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Generate new token with repo scope
3. Copy the token immediately
Configure in .npmrc:
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PATOr embed in package.json URL (less secure):
{
"dependencies": {
"private-package": "git+https://TOKEN:[email protected]/owner/repo.git"
}
}For GitHub Actions, GitLab CI, or Docker builds:
GitHub Actions:
- name: Install dependencies
env:
GIT_CREDENTIALS_FILE: /tmp/.git-credentials
run: |
echo "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com" > $GIT_CREDENTIALS_FILE
git config --global credential.helper "store --file=$GIT_CREDENTIALS_FILE"
npm installDocker (using build secrets):
RUN --mount=type=secret,id=github_token \
git config --global credential.helper "store" && \
npm installImportant: Never commit tokens to version control.
If using multiple Git hosts, configure SSH to use different keys:
Create or edit ~/.ssh/config:
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/github_id_ed25519
IdentitiesOnly yes
Host gitlab.com
HostName gitlab.com
User git
IdentityFile ~/.ssh/gitlab_id_ed25519Ensure SSH agent has keys loaded:
ssh-add ~/.ssh/github_id_ed25519
ssh-add ~/.ssh/gitlab_id_ed25519If you have 2FA enabled and git cannot prompt interactively:
For HTTPS access, you MUST use a Personal Access Token (regular passwords no longer work):
- Create a PAT with repo scope
- Configure in .npmrc or environment variable
- Do NOT use your GitHub password
For SSH access, 2FA does not apply—SSH keys work normally even with 2FA enabled.
SSH vs HTTPS Trade-offs:
- SSH: No token/password exposed, works offline, better for development
- HTTPS: Works everywhere HTTP is available, easier in CI/containers
Security Best Practices:
- Never commit credentials to git
- Use read-only tokens with minimal permissions
- Rotate tokens regularly
- For CI systems, use short-lived tokens or service accounts
Debugging:
GIT_SSH_COMMAND="ssh -vvv" npm installThis shows detailed SSH authentication information.
npm ERR! code E401 npm ERR! 401 Unauthorized - Token has expired
Token has expired - npm authentication failure
npm ERR! code EAI_NODATA npm ERR! errno EAI_NODATA npm ERR! getaddrinfo EAI_NODATA registry.npmjs.org
How to fix "npm ERR! code EAI_NODATA - getaddrinfo EAI_NODATA"
npm ERR! code EMPTYPACKAGE npm ERR! Package contains no files
How to fix 'npm ERR! code EMPTYPACKAGE' - Package contains no files
npm ERR! code EWORKSPACEMISSING npm ERR! Workspace does not exist: packages/missing
How to fix "npm ERR! code EWORKSPACEMISSING - Workspace does not exist" error
npm ERR! code EADDRNOTAVAIL npm ERR! errno EADDRNOTAVAIL npm ERR! Address not available
How to fix "npm ERR! code EADDRNOTAVAIL - Address not available" error