Error messages

“npm error code ETIMEDOUT” on Mac

Q: How long does npm wait?

npm's documentation gives a default fetch-timeout of 300000 ms, five minutes, and 2 fetch-retries.

ETIMEDOUT means that the other side did not answer in time. Node.js documentation says: “the connected party did not properly respond after a period of time.”

Applies to: npm 10 and later print “npm error”. Older versions print “npm ERR!”. All current macOS versions.Checked: 29 October 2026

Symptoms

npm install stops with npm error code ETIMEDOUT.
npm adds that this is a problem related to network connectivity.
It fails on one network, such as a company network or a hotspot.

Likely causes

A proxy that npm does not know. On a network that needs a proxy, npm needs its proxy and https-proxy settings.
A registry that you cannot reach. An old registry setting can point to a private server.
A slow or lossy connection. Large packages time out on a weak Wi-Fi or a hotspot.
A broken IPv6 path. The registry has an IPv6 address, and IPv6 does not work on your network.

How to check

Show npm's registry and proxy settings.

npm config get registry
npm config get proxy
npm config get https-proxy

Ask the registry for an answer.
```
npm ping
```
Test the registry with curl, IPv4 only.
```
curl -4 -I https://registry.npmjs.org/
```
Measure the connection.
```
networkQuality
```

How to fix it

If the network needs a proxy, set it for npm.

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

Remove an old registry setting, so npm uses its default.
```
npm config delete registry
```
Give npm more retries on a slow connection.
```
npm config set fetch-retries 5
```
Run the install again on a faster network, if you can.

With Kilobat

Kilobat's connection doctor tests the registry layer by layer: network, proxy, DNS, rules, IPv4, IPv6, TLS and the server. It names the layer that failed.
```
kilobat why https://registry.npmjs.org/
```
Check if the network is metered, on a VPN or slow before a large install.
```
kilobat conditions
```
These Kilobat checks are free. AI agents run them through MCP with diagnose_connection and diagnose_network. See Find why one site or API won't connect.

Questions

How long does npm wait?

npm's documentation gives a default fetch-timeout of 300000 ms, five minutes, and 2 fetch-retries.

Sources

Node.js documentation: Common system errors
npm Docs: config
curl(1) and networkQuality(8), man page installed with macOS 27.2

Sources checked on 29 October 2026. Man pages are the ones installed with macOS; open one with man <name> in Terminal.