Mensagens de erro

“npm error code ETIMEDOUT” no Mac

Q: Quanto tempo o npm espera?

A documentação do npm informa o fetch-timeout padrão de 300000 ms, cinco minutos, e 2 fetch-retries.

ETIMEDOUT significa que o outro lado não respondeu a tempo. A documentação do Node.js diz que a parte conectada não respondeu adequadamente após um período.

Aplica-se ao npm 10 e posteriores, que mostram “npm error”. Versões anteriores mostram “npm ERR!”. Todas as versões atuais do macOS.Verificado: 29 de outubro de 2026

Sintomas

npm install para com npm error code ETIMEDOUT.
O npm acrescenta que isso é um problema relacionado à conectividade de rede.
Falha em uma rede específica, como uma rede corporativa ou um acesso pessoal.

Possíveis causas

Um proxy que o npm não conhece. Em uma rede que exige proxy, o npm precisa dos ajustes proxy e https-proxy.
Um registro inacessível. Um ajuste registry antigo pode apontar para um servidor privado.
Uma conexão lenta ou com perdas. Pacotes grandes atingem o tempo limite em Wi-Fi fraco ou acesso pessoal.
Um caminho IPv6 com problema. O registro tem um endereço IPv6 e o IPv6 não funciona na sua rede.

Como verificar

Mostre os ajustes de registro e proxy do npm.

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

Peça uma resposta ao registro.
```
npm ping
```
Teste o registro com curl, usando apenas IPv4.
```
curl -4 -I https://registry.npmjs.org/
```
Meça a conexão.
```
networkQuality
```

Como corrigir

Se a rede precisar de proxy, configure-o para o npm.

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

Remova um ajuste antigo de registro para que o npm use o padrão.
```
npm config delete registry
```
Configure mais tentativas para o npm em uma conexão lenta.
```
npm config set fetch-retries 5
```
Execute a instalação novamente em uma rede mais rápida, se puder.

Com o Kilobat

O diagnóstico de conexão do Kilobat testa o registro camada por camada: rede, proxy, DNS, regras, IPv4, IPv6, TLS e servidor. Ele identifica a camada que falhou.
```
kilobat why https://registry.npmjs.org/
```
Verifique se a rede tem limite de dados, usa uma VPN ou é lenta antes de uma instalação grande.
```
kilobat conditions
```
Essas verificações do Kilobat são gratuitas. Agentes de IA as executam pelo MCP com diagnose_connection e diagnose_network. Consulte Descubra por que um site ou API não conecta.

Perguntas

Quanto tempo o npm espera?

A documentação do npm informa o padrão fetch-timeout de 300000 ms, cinco minutos, e 2 fetch-retries.

Um ajuste de proxy pode afetar downloads do npm?

Sim. O npm tem configuração de proxy, e um proxy inacessível ou incorreto pode impedir a conexão com um registro.

Fontes

Documentação do Node.js: erros de sistema comuns
Documentação do npm: config
curl(1) e networkQuality(8), páginas de manual instaladas com o macOS 27.2

Verificado em 29 de outubro de 2026.