This error occurs when npm can't find a package on GitHub Packages registry. Usually an authentication issue—GitHub Packages returns 404 instead of 401 to hide whether private packages exist.
GitHub Packages is GitHub's npm registry for hosting private and public packages. Unlike the main npm registry, GitHub Packages requires authentication even for public packages. The tricky part: GitHub returns a 404 error instead of 401 when authentication fails. This is intentional—it prevents unauthorized users from discovering whether private packages exist. So when you see "404 Not Found," the package usually does exist; you just don't have proper authentication configured. This error is extremely common when setting up GitHub Packages for the first time or in CI/CD pipelines.
Generate a PAT with package read access:
1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Click "Generate new token (classic)"
3. Select scopes: read:packages, repo (for private repos)
4. Copy the token immediately (you won't see it again)
Create or edit ~/.npmrc in your home directory:
//npm.pkg.github.com/:_authToken=YOUR_PERSONAL_ACCESS_TOKEN
@YOUR-ORG:registry=https://npm.pkg.github.comReplace:
- YOUR_PERSONAL_ACCESS_TOKEN with your PAT
- YOUR-ORG with your GitHub organization or username
Important: The scope (@YOUR-ORG) must match the package scope exactly.
For better security, use an environment variable:
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
@YOUR-ORG:registry=https://npm.pkg.github.comThen set NODE_AUTH_TOKEN in your environment or CI/CD secrets.
For GitHub Actions, use the built-in setup:
- uses: actions/setup-node@v4
with:
node-version: '20'
registry-url: 'https://npm.pkg.github.com'
scope: '@your-org'
- run: npm ci
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}Note: GITHUB_TOKEN only works for packages in the same repository. For cross-repo packages, use a PAT stored in secrets.
Check your npm configuration:
npm config get @your-org:registry
# Should show: https://npm.pkg.github.com
npm config list
# Verify no conflicting settingsGITHUB_TOKEN Limitations: The built-in GITHUB_TOKEN in GitHub Actions can only access packages from the same repository. For packages from other repos in your organization, you need a Personal Access Token with read:packages scope.
Public Packages Still Need Auth: Unlike npmjs.com, GitHub Packages requires authentication even for public packages. This is a common surprise.
Repository Field: Packages must have a repository field in package.json matching the GitHub repo where they're published:
{
"repository": {
"type": "git",
"url": "https://github.com/your-org/your-repo.git"
}
}Multiple Registries: You can use both npm and GitHub Packages by scoping:
@your-org:registry=https://npm.pkg.github.com
registry=https://registry.npmjs.orgnpm ERR! code ENOAUDIT npm ERR! Audit endpoint not supported
How to fix "npm ERR! code ENOAUDIT - Audit endpoint not supported"
npm ERR! code EBADDEVENGINES npm ERR! devEngines.runtime incompatible with current node version
How to fix "npm ERR! code EBADDEVENGINES - devEngines.runtime incompatible with current node version"
npm ERR! code ETOOMANYARGS npm ERR! Too many arguments
How to fix "npm ERR! code ETOOMANYARGS - Too many arguments"
npm ERR! code EINVALIDTAGNAME npm ERR! Invalid tag name: tag names cannot contain spaces
How to fix "npm ERR! code EINVALIDTAGNAME - tag names cannot contain spaces"
npm ERR! code E400 npm ERR! 400 Bad Request
How to fix "npm ERR! code E400 - 400 Bad Request" error