npm install returns 401 for a private package on GitLab
npm ERR! 401 UnauthorizedShort answer
GitLab answers 401 when npm sends no token or one it does not accept. Check that the token has the right scope (api for personal, group or project tokens; read_package_registry for deploy tokens), that your NPM_TOKEN variable is set, and that the scope and token lines in .npmrc use the same registry URL.
Fix it fast
1Find out which cause you have
Ask npm which registry it will use for your scope and whether the token variable has a value.
npm config get @my-scope:registry test -n "$NPM_TOKEN" && echo "NPM_TOKEN is set" || echo "NPM_TOKEN is empty"2Match what you see, then jump to its fix
- 1
The variable is set and the URL is right, but GitLab still answers 401The token has the wrong type or scopeFix - 2
npm config get @my-scope:registry prints the public registry or nothingThe .npmrc does not link the scope, the URL and the tokenFix - 3
A pasted token that expired, or a CI job that has no such fileThe token is written into .npmrc instead of read from the environmentFix
- 1
What does the error look like?
npm ERR! 401 Unauthorized
Cause 1 of 3
The token has the wrong type or scope
1Check
GitLab's docs require the api scope for a personal, group or project access token, and read_package_registry or write_package_registry for a deploy token. When two-factor authentication is enforced you must use a personal access token with the api scope.
echo "$NPM_TOKEN" | wc -c2Fix
Create a new token with the right scope in GitLab and export it as NPM_TOKEN. Use a deploy token with read_package_registry for installs only.
export NPM_TOKEN=<token from GitLab>3Verify
Install again.
npm installConfirmed by docs.gitlab.com
Cause 2 of 3
The .npmrc does not link the scope, the URL and the token
1Check
npm needs two lines: one that maps the scope to the GitLab endpoint, and one that gives the token for exactly that endpoint. GitLab shows a project-level form and an instance-level form.
cat .npmrc2Fix
Write both lines with the same endpoint. The project form is shown here; the instance form uses /api/v4/packages/npm/ and needs the package scoped to the top-level group.
@my-scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
//gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"3Verify
The scope now maps to the GitLab address.
npm config get @my-scope:registryConfirmed by docs.gitlab.com
Cause 3 of 3
The token is written into .npmrc instead of read from the environment
1Check
GitLab warns against hardcoding tokens in .npmrc. The token line should read the NPM_TOKEN variable, so each machine and CI job supplies its own.
grep -n "_authToken" .npmrc2Fix
Replace the pasted value with the variable and set that variable in the CI settings.
//gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"3Verify
A fresh install works on a clean machine with only the variable set.
NPM_TOKEN=<token> npm installConfirmed by docs.gitlab.com
How do I stop it coming back?
- Give deploy tokens an expiry you can see, and renew them before it passes.
- Use read-only deploy tokens for installs and a separate write token for publishing.
- Keep only the scope and the ${NPM_TOKEN} reference in the committed .npmrc.
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?
Projects of mine built on the same technologies:
Related fixes
Back end
npm install fails with E401 against a private Nexus registry
npm error Unable to authenticate, need: BASIC realm="Sonatype Nexus Repository Manager"
E401 means the registry asked for credentials and npm sent none that it accepts.
4 causes, each with a fixServers
npm install returns 401 for a GitHub Packages package in a workflow
npm install works on your laptop but fails in the workflow run
The install step reached npm.pkg.github.com without a valid token.
3 causes, each with a fixBack end
ng serve says it cannot determine the project or target
Cannot determine project for command.
The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.
3 causes, each with a fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack end
ng serve cannot find the dev-server builder package
Could not find the implementation for builder @angular/build:dev-server
The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.
3 causes, each with a fix