---
title: "npm error code ETIMEDOUT on Mac: fix npm network timeouts · Kilobat Guides"
url: "https://kilobat.app/guides/npm-etimedout.html"
description: "npm install on your Mac stops with npm error code ETIMEDOUT. Check the registry, the proxy and the connection, then change npm's settings."
---

Error messages

# “npm error code ETIMEDOUT” on Mac

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

1. Show npm's registry and proxy settings.

   ```
   npm config get registry
   npm config get proxy
   npm config get https-proxy
   ```
2. Ask the registry for an answer.

   ```
   npm ping
   ```
3. Test the registry with curl, IPv4 only.

   ```
   curl -4 -I https://registry.npmjs.org/
   ```
4. Measure the connection.

   ```
   networkQuality
   ```

## How to fix it

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

   ```
   npm config set https-proxy http://proxy.example.com:8080
   ```
2. Remove an old registry setting, so npm uses its default.

   ```
   npm config delete registry
   ```
3. Give npm more retries on a slow connection.

   ```
   npm config set fetch-retries 5
   ```
4. Run the install again on a faster network, if you can.

## With Kilobat

1. 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/
   ```
2. Check if the network is metered, on a VPN or slow before a large install.

   ```
   kilobat conditions
   ```
3. 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](https://kilobat.app/guides/recipes/why-cant-it-connect.html).

## 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](https://nodejs.org/api/errors.html#common-system-errors)
- [npm Docs: config](https://docs.npmjs.com/cli/v11/using-npm/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.

## Related guides

- [“npm error code ECONNRESET” on Mac](https://kilobat.app/guides/npm-econnreset.html): ECONNRESET means that the other side closed the connection by force.
- [Homebrew or npm downloads fail on a Mac](https://kilobat.app/guides/homebrew-npm-download-fails.html): Homebrew downloads with curl and Git.
- [Proxy settings stop apps from connecting on a Mac](https://kilobat.app/guides/proxy-settings-breaking-apps.html): A proxy setting sends traffic through another server.
- [Corporate proxy certificates break Terminal tools on a Mac](https://kilobat.app/guides/corporate-proxy-certificates.html): Some company networks inspect HTTPS traffic.
- [Check the network before a big download in an agent](https://kilobat.app/guides/recipes/check-network-before-download.html): An agent can ask Kilobat if now is a good time for a large transfer.