Maaz Zindani

Loading the index…

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

npm cannot reach the registry from behind a proxy

ErrorETIMEDOUT

Short answer

npm needs to be told about your proxy. Set proxy and https-proxy (or the HTTP_PROXY and HTTPS_PROXY variables), exclude internal hosts with noproxy, and if the proxy inspects TLS, give npm its CA file with cafile. Disabling strict-ssl is not the fix.

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

Fix it fast

  1. 1Find out which cause you have

    Print what npm currently uses for proxy and registry, and what your shell exports.

    npm config get proxy
    npm config get https-proxy
    npm config get registry
    env | grep -i proxy
  2. 2Match what you see, then jump to its fix

    1. 1Timeouts or refused connections, while a browser on the same network worksNo proxy is set, so npm tries to connect directlyFix
    2. 2Public packages install, but a private registry or internal host failsInternal hosts are sent through the proxyFix
    3. 3A certificate error appears once the proxy itself is reachedThe proxy re-signs TLS and npm does not trust its certificateFix

What does the error look like?

  • ETIMEDOUT
  • ECONNREFUSED

Cause 1 of 3

No proxy is set, so npm tries to connect directly

1Check

Both npm proxy settings default to null. npm also honours HTTP_PROXY and HTTPS_PROXY variables, so one of those or the config must be set.

npm config get proxy
npm config get https-proxy

2Fix

Set both options to your proxy URL.

npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

3Verify

Ask the registry for a package's version.

npm view npm version

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

Internal hosts are sent through the proxy

1Check

noproxy lists domain extensions that bypass any proxy. Its default is the NO_PROXY variable.

npm config get noproxy

2Fix

Add your internal domain to noproxy.

npm config set noproxy localhost,.corp.example.com

3Verify

Install from the internal registry again.

npm view my-private-package version

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 3

The proxy re-signs TLS and npm does not trust its certificate

1Check

strict-ssl (default true) makes npm validate the registry's certificate. A company proxy that inspects traffic uses its own CA, which npm does not know.

npm config get cafile

2Fix

Point cafile at the PEM file with your company's CA certificates. Keep strict-ssl on.

npm config set cafile /etc/ssl/certs/company-ca.pem

3Verify

Run the install again.

npm view npm version

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Keep proxy settings in the user .npmrc, not in each project, and never commit credentials in a proxy URL.
  • Ask your network team for the CA bundle once and store it in a known path.
  • Keep a private registry's domain in noproxy.

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.