Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

npm install returns 401 for a GitHub Packages package in a workflow

Error401 Unauthorized from https://npm.pkg.github.com

Short answer

The install step reached npm.pkg.github.com without a valid token. Set the registry and scope with actions/setup-node, pass a token through NODE_AUTH_TOKEN on the install step, and make sure the token can read the package: packages read permission, and repository access if the package belongs to another repo.

  • Applies to GitHub Actions, actions/setup-node, npm 10, GitHub Packages npm registry
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the failing run and look at the registry URL in the error, and at the install step's env. Then check what .npmrc the job wrote.

    npm config get @my-org:registry
    cat .npmrc
  2. 2Match what you see, then jump to its fix

    1. 1401 on the first request, and the install step has no NODE_AUTH_TOKENThe install step has no token for npm.pkg.github.comFix
    2. 2The token is set, but the workflow or job has a permissions: key without packagesA permissions block removed the packages scope from GITHUB_TOKENFix
    3. 3Token and permissions are right, still 401 or 403 for one package onlyThe package belongs to another repository and this repository has no accessFix

What does the error look like?

  • 401 Unauthorized from https://npm.pkg.github.com
  • npm install works on your laptop but fails in the workflow run

Cause 1 of 3

The install step has no token for npm.pkg.github.com

1Check

setup-node writes an .npmrc that reads the token from the NODE_AUTH_TOKEN variable. If the variable is not set on the step that runs npm, the request goes out unauthenticated.

grep -n -E 'registry-url|scope|NODE_AUTH_TOKEN' .github/workflows/*.yml

2Fix

Set registry-url and scope in setup-node and pass the token as an environment variable on the install step. The scope is the owner of the package.

- uses: actions/setup-node@v7
  with:
    node-version: '22'
    registry-url: 'https://npm.pkg.github.com'
    scope: '@my-org'
- run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

3Verify

The install step downloads the package without an E401.

npm ls @my-org/my-package

Confirmed by docs.github.com

Did this fix it?

Cause 2 of 3

A permissions block removed the packages scope from GITHUB_TOKEN

1Check

Once any scope is listed under permissions, every unlisted scope is set to none.

grep -n -B1 -A4 'permissions:' .github/workflows/*.yml

2Fix

Add the packages scope with read access, next to contents: read for checkout.

permissions:
  contents: read
  packages: read

3Verify

Re-run the job; the package request is now authenticated with access to packages.

npm view @my-org/my-package version

Confirmed by docs.github.com

Did this fix it?

Cause 3 of 3

The package belongs to another repository and this repository has no access

1Check

GITHUB_TOKEN can read a package from another repository only if that repository is granted read access to the package.

grep -n -E 'NODE_AUTH_TOKEN|secrets' .github/workflows/*.yml

2Fix

In the package's settings, use Manage Actions access and add the repository that runs the workflow. Otherwise use a personal access token (classic) with the read:packages scope, stored as a repository secret.

env:
  NODE_AUTH_TOKEN: ${{ secrets.PACKAGES_READ_TOKEN }}

3Verify

Run npm ci again and confirm the package installs.

npm ci

Confirmed by docs.github.com

Did this fix it?

How do I stop it coming back?

  • Prefer GITHUB_TOKEN with the least permissions over a long-lived personal access token.
  • Keep the scope-to-registry line in a committed .npmrc and the token only in the workflow environment.
  • When you add a new repository that consumes the package, grant it access in the package settings the same day.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Servers

docker pull or push to ghcr.io fails with 'denied'

Error response from daemon: denied

ghcr.io refuses a pull or push when Docker is not logged in, when the token lacks the package scope, or when the workflow's GITHUB_TOKEN has no packages permission or no access to that package.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.