npm proxy settings: npmrc, precedence and install failures

For npm registry traffic, inspect both proxy and https-proxy, choose one approved gateway, and test the package download as well as registry access. A successful npm ping is insufficient to prove an installation will work. In our controlled test, ping and package metadata succeeded while the tarball request failed.

This guide's observations use npm11.19.1, Node26.10.0 and macOS15.7.4, recorded on 12 October 2026. Nine routing cases and four configuration-edit checks passed their stated acceptance criteria. The fixtures use an HTTP registry and forwarding proxies on loopback; they do not test HTTPS, certificates, proxy authentication or a commercial service.

Distinguish the gateway from the registry

registry identifies the service supplying package metadata. proxy and https-proxy configure the network gateway used to reach it. A Nexus “npm proxy repository” is a repository manager/cache exposed as an npm registry; it is a different layer from a forward HTTP proxy. Use your organization's registry URL and gateway as separate inputs. Sonatype npm configuration, npm configuration.

Start inside the project where the failure occurs:

node --version
npm --version
npm config get registry
npm config get proxy https-proxy noproxy
npm config get userconfig globalconfig

Inspect this output locally; proxy URLs can contain credentials. The registry URL is not evidence of the network route. Neither are null proxy values: our raw HTTP_PROXY case still used a proxy while npm displayed null for both configuration keys.

Test registry access, metadata and the archive

After inspecting the failing project, choose four explicit inputs: NPM_PROXY_URL for the approved gateway, NPM_REGISTRY_URL for the approved registry, NPM_PACKAGE for an unscoped package pinned as NAME@VERSION, and NPM_USERCONFIG for an approved absolute npmrc path. The userconfig path reported above is a starting point; ensure the chosen file supplies any required registry authentication. No tokens need to be copied into the diagnostic directory.

For a private or scoped package, the approved configuration must preserve the appropriate registry and registry-scoped authentication. An @scope:registry entry is a distinct setting: do not assume the default --registry overrides it. Confirm the metadata's archive URL and the actual registry used. The basic commands below choose an unscoped package to isolate the gateway check. npmrc scope and authentication.

An HTTP gateway may be used for an HTTPS registry; the gateway URL's scheme identifies its own connection protocol. Keep actual secrets out of shell-history literals and shared logs. Environment substitution does not conceal the expanded argument from local process inspection.

Run all three checks in one new directory outside existing projects. Keep the same registry, approved config and proxy values, with a new cache path for each request stage:

npm_proxy_check_dir="$(mktemp -d)"
cd "$npm_proxy_check_dir" || exit 1

npm ping --proxy="$NPM_PROXY_URL" --https-proxy="$NPM_PROXY_URL" \
  --registry="$NPM_REGISTRY_URL" --userconfig="$NPM_USERCONFIG" \
  --cache="$npm_proxy_check_dir/cache-ping" \
  --fetch-retries=0 --fetch-timeout=10000

npm view "$NPM_PACKAGE" version dist.tarball --json \
  --proxy="$NPM_PROXY_URL" --https-proxy="$NPM_PROXY_URL" \
  --registry="$NPM_REGISTRY_URL" --userconfig="$NPM_USERCONFIG" \
  --cache="$npm_proxy_check_dir/cache-view" \
  --fetch-retries=0 --fetch-timeout=10000

ping probes the registry; view reads metadata, including the archive URL. Neither downloads and verifies the package archive. npm ping, npm view.

For the third check, stay in that diagnostic directory and use the same inputs:

npm install "$NPM_PACKAGE" --ignore-scripts --no-audit --no-fund \
  --no-package-lock --save=false \
  --proxy="$NPM_PROXY_URL" --https-proxy="$NPM_PROXY_URL" \
  --registry="$NPM_REGISTRY_URL" --userconfig="$NPM_USERCONFIG" \
  --cache="$npm_proxy_check_dir/cache-install" \
  --fetch-retries=0 --fetch-timeout=10000

Inspect the installed package's expected name, version and contents. Our fixture checks exact payload files, rather than accepting an HTTP200 or successful metadata response. The fresh installation cache prevents a previously cached archive from silently satisfying this check. Also verify the gateway's request logs when available: a valid package alone does not prove which route carried it. Keep the diagnostic output for review and remove the temporary directory when finished.

The install disables package installation scripts. It checks registry-package retrieval, not every dependency or a project's complete installation behavior. fetch-timeout and disabled fetch retries bound individual fetch behavior; they are not a ten-second deadline for the whole installation. npm install, npm fetch options.

Resolve configuration conflicts before saving settings

For the same key, npm's documented priority runs from command options to npm_config_* environment values, then project, user and global configuration. The project's .npmrc can keep overriding a new user setting. Project configuration is not read in global install mode. Pinned npm configuration hierarchy, npmrc files.

That hierarchy does not settle conflicts between different keys. In our npm11.19.1 case, a user https-proxy=A remained active despite a command --proxy=B. Both values survived configuration resolution, and the registry fetch implementation selected httpsProxy || proxy—even for our HTTP registry. Inspect and align both keys when you intend one gateway. Pinned registry fetch implementation.

After the temporary test works, save credential-free illustrative values to the intended file:

npm config set proxy=http://proxy.example:8080 \
  https-proxy=http://proxy.example:8080 --location=user

Use --location=project from the relevant project if that is the desired scope. Keep credentials out of committed .npmrc files. npmrc supports environment substitutions for values; a configuration lookup can still display the expanded value. Registry tokens also have their own registry scope and are not proxy credentials. npmrc authentication and substitutions.

What our routing fixture showed

The routing lab creates a fake registry and proxies A/B, serves a real generated package archive and records each actual request. The results include exact command arguments, configuration and payload acceptance.

Eight installations verified the expected package payload. The ninth was an intentional failure with no installed payload; all nine cases met their defined acceptance criteria. Raw environment fallback comes from the tested agent implementation. The bypass observation covers only the exact IPv4 loopback hostname, not wildcard, CIDR or every client. Pinned npm agent.

Remove values from the intended file

Inspect the project .npmrc and the user/global paths reported earlier. If you meant to remove the example user settings:

npm config delete proxy https-proxy --location=user

A project entry can still win. Remove project settings only when that is intended, from the project directory:

npm config delete proxy https-proxy --location=project

Our four separate configuration-edit checks show that deleting user keys preserved the project's values; deleting the project keys then removed the effective pair in that isolated configuration. npm's documentation says deletion removes keys from all files, but the pinned npm11.19.1 implementation and our experiment act on the selected location. Use explicit scope and verify the result. Pinned deletion implementation, npm config documentation.

Also inspect the actual process's npm_config_proxy, npm_config_https_proxy, HTTP_PROXY, HTTPS_PROXY and bypass variables. Removing file entries does not remove environment values. The environment variables guide explains how inherited settings differ by client.

Diagnose remaining failures

For corporate CA trust, npm documents cafile and strict-ssl. Obtain the approved CA bundle from your administrator and keep strict-ssl enabled. The HTTP fixtures do not verify any HTTPS or corporate trust fix. npm certificate configuration.

Reproduce the two experiments

Download the two scripts and README into one directory, then run with Node and npm installed:

node npm-proxy-lab.mjs ./local-results.json
node npm-config-edit-check.mjs ./local-config-results.json

The configuration script and config results accompany the routing evidence. They use explicit temporary user/global config paths and caches, preserve your original user configuration and confine network requests to loopback. The recorded environment was npm11.19.1/Node26.10.0; the current v11 docs display a newer version, so rerun before generalizing to another release. No extra npm packages are required to run these fixtures. HTTPS/CONNECT, proxy credentials, private registry authentication, Git dependencies, existing lockfiles and lifecycle downloads remain outside the experiment.

If you are evaluating ipvolt for future proxy workflows, Know when access opens. One email when access opens. Nothing else.