npm Proxy Settings: Fix ECONNRESET, ETIMEDOUT, 407, and "You Are Behind a Proxy" Errors

Every npm network failure ends the same way: "npm ERR! network This is a problem related to network connectivity. npm ERR! network In most cases you are behind a proxy or have bad network settings. npm ERR! network If you are behind a proxy, please make sure that the 'proxy' config is set properly." It is a footer, printed for any error in the network family, and it has sent a great many people on a home connection looking for a proxy they do not have. The line above the footer is the diagnosis: ECONNRESET, ETIMEDOUT, ECONNREFUSED, ENOTFOUND, a 407, or one of the certificate codes. Each has a different cause and a different fix, and only some of them involve a proxy at all.

This guide covers how npm decides where to send its traffic, the .npmrc keys and environment variables, the certificate fix that corporate proxies require, and each error line in turn, then the equivalents for yarn and pnpm.

How npm finds a proxy

npm looks at its own configuration first and the environment second.

• Config keys. proxy is used for plain HTTP requests and https-proxy for HTTPS ones, which in practice means the registry, since registry.npmjs.org is HTTPS. Both take the proxy's URL. For a normal corporate proxy both values begin with http://, because the key names the traffic the proxy carries, not the scheme the proxy speaks. noproxy lists hosts that bypass the proxy.
• Where keys live. A project .npmrc in the directory tree, then the user .npmrc in your home folder, then the global one, then npm's built-in defaults. npm config ls -l prints every setting and, with --json, is easy to search; npm config get proxy and npm config get https-proxy show the resolved values.
• Environment variables. With the keys unset, npm honours HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (and their lower-case forms), so a proxy exported in the shell is an npm proxy with no .npmrc involvement. This is also the usual hiding place for a proxy nobody remembers setting.

Setting and removing it

Set:

npm config set proxy http://alice:p%40ss@proxy.example.com:3128
npm config set https-proxy http://alice:p%40ss@proxy.example.com:3128
npm config set noproxy "localhost,127.0.0.1,.corp,registry.internal.example.com"

Special characters in the password are URL-encoded; the @ in p@ss becomes %40, or npm reads the rest of the value as the hostname.

Remove:

npm config delete proxy
npm config delete https-proxy
npm config get proxy

Then clear the environment for the session (unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy) and take the export out of the shell profile (or the system variables on Windows), or the proxy is back with the next terminal.

The errors

ECONNRESET

The registry connection was opened and then cut. On a corporate network this is the signature of a proxy or firewall that only permits HTTPS it can inspect: direct connections are reset, and connections through the proxy work once npm trusts the proxy's certificate authority. Set proxy and https-proxy, then do the certificate step below. On a home connection, an ECONNRESET is more often an antivirus web shield, a VPN, or a flaky connection, and the fix is to turn those off one at a time and retry.

ETIMEDOUT and ERR_SOCKET_TIMEOUT

Nothing answered. Behind a corporate proxy with no proxy configured, npm is trying to reach the registry directly, and the network is silently dropping it: set the proxy. With a proxy configured, the proxy address or port is wrong, or the proxy is unreachable from this network: test it with curl -v -x http://proxy.example.com:3128 https://registry.npmjs.org/ and read the result. Raising fetch-timeout and fetch-retries helps only with a slow but working path, not with a blocked one.

ECONNREFUSED on 127.0.0.1

The tell of a leftover. A debugging proxy such as Fiddler or Charles sets the system or environment proxy to a local port while it runs, and some tools do not put it back. npm now sends everything to that port, and nothing is listening. Run npm config ls -l | grep -i proxy and env | grep -i proxy to find which layer holds the value, and delete it there. The system-level version of the same leftover is in how to turn off a proxy.

407 Proxy Authentication Required

The proxy needs a login. npm does not prompt; the credentials ride inside the proxy URL, with special characters encoded. Proxies that require NTLM or Kerberos rather than Basic cannot be satisfied this way, and the usual answer is a helper process on your machine that logs in to the corporate proxy with your Windows identity and offers npm an unauthenticated proxy on 127.0.0.1. 407 Proxy Authentication Required covers the encoding traps.

The certificate errors

UNABLE_TO_GET_ISSUER_CERT_LOCALLY and SELF_SIGNED_CERT_IN_CHAIN mean the proxy is inspecting HTTPS: your connection ends at the proxy, which opens a new one to the registry and presents you a certificate from the organisation's own authority instead of the registry's. Browsers on managed machines trust that authority because IT installed it; Node has its own bundle and does not. Two correct fixes:

npm config set cafile /path/to/corporate-root.pem

or, for every Node program on the machine rather than npm alone:

export NODE_EXTRA_CA_CERTS=/path/to/corporate-root.pem

The file is the authority's root certificate in PEM form, obtainable from IT or exported from the system certificate store. The fix to avoid is npm config set strict-ssl false, which turns off certificate verification for every install; it works, and it means any machine in the middle can hand you any package. Use it once, on a single command, to confirm the diagnosis, and then do the real fix.

ENOTFOUND

DNS failed for the registry hostname. On a network that only allows resolution through the proxy, setting the proxy fixes it, because the proxy resolves names on your behalf. Elsewhere it is a DNS problem unrelated to npm: nslookup registry.npmjs.org will fail the same way, and the connection's DNS settings are the fix.

EPROTO, wrong version number

An https:// scheme in https-proxy makes npm start a TLS handshake with the proxy itself. Most proxies speak plain HTTP on their listening port and answer TLS with garbage, which Node reports as a protocol error. Set the scheme to http://; the key's name is about the traffic, not the proxy.

yarn, pnpm, and npx

pnpm reads the same .npmrc keys, so the proxy and https-proxy values above cover it. npx runs through npm's configuration. Yarn 1 keeps its own store: yarn config set proxy http://... and yarn config set https-proxy http://.... Yarn 2 and later use .yarnrc.yml with httpProxy and httpsProxy, plus caFilePath for the certificate and enableStrictSsl as the equivalent of strict-ssl. All of them honour HTTP_PROXY and HTTPS_PROXY in the environment, which makes the environment the one place to set a proxy that every tool sees.

A proxy for npm is not a proxy for your code

A frequent confusion: setting npm's proxy does nothing for the programs npm installs. A Node script that calls fetch or axios opens connections of its own and ignores .npmrc entirely; it needs an agent of its own. Our guides to proxies in Node.js, node-fetch, and axios cover that side, including the httpsAgent trap in axios that produces its own set of confusing errors.

Five things to remember

Read the line above npm's footer, not the footer. npm config ls -l and env | grep -i proxy show every proxy in play. Set proxy and https-proxy with http:// schemes and encoded credentials; delete them and clear the environment to remove. Give npm the corporate authority through cafile instead of switching strict-ssl off. And an ECONNREFUSED on 127.0.0.1 is a debugging proxy that forgot to leave.