Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

npm install returns 401 for a private package on GitLab

Errornpm ERR! 401 Unauthorized

Short 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.

  • Applies to npm 10 and 11, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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"
  2. 2Match what you see, then jump to its fix

    1. 1The variable is set and the URL is right, but GitLab still answers 401The token has the wrong type or scopeFix
    2. 2npm config get @my-scope:registry prints the public registry or nothingThe .npmrc does not link the scope, the URL and the tokenFix
    3. 3A pasted token that expired, or a CI job that has no such fileThe token is written into .npmrc instead of read from the environmentFix

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 -c

2Fix

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 install

Confirmed by docs.gitlab.com

Did this fix it?

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 .npmrc

2Fix

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:registry

Confirmed by docs.gitlab.com

Did this fix it?

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" .npmrc

2Fix

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 install

Confirmed by docs.gitlab.com

Did this fix it?

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

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 fix

Back 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

Next step

Want this handled for good?

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