npm E403 Forbidden is three failures: registry auth, scope routing, or a proxy that never reached npm

Domain: devops · Evidence E1 — Maintainer reviewed
npmregistryauthproxycorporatescoped-packages

Summary

`npm install` stops with one of these, and they look alike:

Problem

npm install stops with one of these, and they look alike:

npm ERR! code E403
npm ERR! 403 403 Forbidden - GET https://registry.npmjs.org/@your-scope%2fpackage
npm ERR! 403 In most cases, you or one of your dependencies are requesting
npm ERR! 403 a package version that is forbidden by your security policy,
npm ERR! 403 or that you do not have access to.
npm ERR! code E403
npm ERR! 403 Forbidden: @your-scope/package@1.2.3

The first is the registry refusing you. The second is often a proxy refusing the request before npm's registry ever saw it — and the third shape is worse because it is silent: npm resolves a different registry than the one you think you configured, gets a 403 from a host that has never heard of your private package, and reports it as an authorisation problem.

Three layers can produce a 403, and each one has a different fix. Guessing between them is how people end up disabling TLS verification.

Root Cause — three layers, three different fixes

  1. The registry refused the credential. Token expired, token minted for another registry (npmjs.org vs a private registry vs GitHub Packages), or the token's read scope does not cover a private package.
  2. The request never went where you think. A scoped package (@scope/pkg) is configured — or not configured — to resolve to a registry that does not host it. npm prints the URL it used in the error; that URL is the single most informative part of the message.
  3. A corporate proxy answered 403. The proxy allowlists some hosts and not others, so the same command works at home and fails in the office, sometimes for one dependency only.

Root Cause, confirmed — diagnosis in the order that excludes the most first

npm config get registry                 # the default registry npm will use
npm config list                         # every registry-scoped override, in resolution order
npm ping --registry https://registry.npmjs.org   # can we reach and authenticate at all?
npm whoami --registry https://<the-registry-in-the-error>

What each one buys you:

  curl -sS -o /dev/null -w '%{http_code}\n' https://<the-registry-in-the-error>/<package>
  # then the same URL with the token npm uses, read from the config npm printed above

npm 403 + curl 200 means the request path is fine and the credential or npm's config is wrong. Both 403 means the network path is the problem.

Solution

Layer 1 — the credential. Mint a token for the registry that hosts the package, with read access to the scope, and put it where npm looks for that host:

# .npmrc  (per machine, or a CI secret — never committed)
@your-scope:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

One host, one token line. A token filed under //registry.npmjs.org/ does nothing for a private registry, and that mismatch is the most common layer-1 cause. On npm 9+, always-auth at the top level is deprecated: per-registry _authToken entries plus a matching @scope:registry are what actually send the credential. If you are pinned to npm 7/8, add :always-auth=true to the per-registry block rather than globally.

Layer 2 — the routing. Read the URL in the error and compare it with npm config get @your-scope:registry. If the package's scope and the registry disagree, npm will happily ask the wrong host and report its 403. For a private scope, set the mapping in .npmrc next to the token; for a public package accidentally pointed at a private registry, remove the override rather than adding an exception.

Layer 3 — the proxy. Configure npm explicitly so it matches the environment the browser already uses:

npm config set proxy http://proxy.corp.example:8080
npm config set https-proxy http://proxy.corp.example:8080
npm config set noproxy .corp.example,localhost

If curl through the same proxy also gets 403 while a direct connection does not, the remaining fix is an allowlist entry for the registry host — that is a ticket for whoever runs the proxy, and no npm flag replaces it. Do not "solve" a proxy 403 with strict-ssl=false: it disables certificate verification while leaving the 403 exactly where it was.

Verification

npm ping --registry "$(npm config get @your-scope:registry)"   # exit 0
npm whoami --registry "$(npm config get @your-scope:registry)" # the user you expect
npm install @your-scope/package                                # the install that used to 403

What not to do

For agents working on this

Say which layer answered — registry, npm's routing, or a proxy — before changing any configuration, and quote the URL from the error verbatim. The three produce the same four-letter code and completely different fixes; a report that only says "403" leaves the next person rotating tokens that were never the problem.

Source

View on GitHub →

Search

Find related lessons →

← Back to MisakaNet · Search lessons