Victor's room

Overview & Root Cause Summary: The error npm ERR! code ETIMEDOUT syscall connect ... network request to https://registry.npmjs.org/<package> failed, reason: connect ETIMEDOUT occurs during npm install when the npm CLI fails to establish or maintain a TCP socket connection with the target package registry within the allotted timeout window. The primary root causes include stale or misconfigured HTTP/HTTPS proxy settings, Node.js prioritizing IPv6 DNS resolution on networks lacking IPv6 routing, corporate firewalls or VPNs blocking outbound traffic, or transient upstream registry latency.

Understanding the Root Causes

• Stale or Misconfigured Corporate Proxy Settings: Lingering proxy or https-proxy entries in ~/.npmrc attempting to route traffic through an unreachable proxy server after disconnecting from an enterprise VPN.
• IPv6 DNS Resolution Deadlocks: Node.js (v17+) defaulting to an IPv6-first DNS resolution order (--dns-result-order=verbatim), causing connection attempts to stall indefinitely on ISPs or routers with broken IPv6 routing before timing out.
• Strict Corporate Firewalls & SSL Decryption: Enterprise security gateways or deep packet inspection firewalls dropping outbound HTTPS requests directed at registry.npmjs.org.
• Low Default Fetch Timeout Thresholds: High network latency or large package payloads exceeding npm’s default socket connection timeout.

Step 1: Quick Fix (Force IPv4 Resolution & Extend Fetch Timeout)

Configure Node.js to prioritize IPv4 DNS lookups and instruct npm to extend its socket timeout threshold with automatic retries.

# 1. Force Node.js to use IPv4 resolution first in your active shell:
export NODE_OPTIONS="--dns-result-order=ipv4first"

# 2. Run npm install with extended fetch timeout (e.g. 5 minutes) and retry attempts:
npm install --fetch-timeout=300000 --fetch-retries=5

# 3. Add the IPv4 preference permanently to your shell profile (~/.bashrc or ~/.zshrc):
echo 'export NODE_OPTIONS="--dns-result-order=ipv4first"' >> ~/.zshrc
source ~/.zshrc

Step 2: Audit and Clear Proxy Configurations in .npmrc

Inspect your npm configuration for outdated proxy declarations and remove them if working outside of a corporate network.

# 1. Check for any active proxy settings:
npm config get proxy
npm config get https-proxy

# 2. If disconnected from the corporate VPN, delete stale proxy settings:
npm config delete proxy
npm config delete https-proxy

# 3. If a corporate proxy is genuinely required, configure valid credentials:
npm config set proxy http://username:password@proxy.company.com:8080
npm config set https-proxy http://username:password@proxy.company.com:8080

# 4. Ensure registry URL is pointed directly to official npmjs:
npm config set registry https://registry.npmjs.org/

Step 3: Alternative Approach (Registry Ping & Mirror Fallback)

Test connectivity directly with the registry endpoint, clear corrupted local cache, or switch temporarily to an official CDN mirror.

# 1. Test ping connectivity to the registry:
npm ping

# 2. Force purge npm's network and metadata cache:
npm cache clean --force

# 3. If official npmjs is experiencing upstream outage, test via Cloudflare mirror:
npm install --registry=https://registry.yarnpkg.com

Verification & Testing Steps

Confirm that npm connects cleanly to the package registry and successfully downloads package metadata without network timeouts.

# 1. Ping the active registry endpoint:
npm ping

# 2. Verify registry connectivity by viewing package metadata:
npm view express version

# 3. Execute dependency installation:
npm install

Summary Comparison Table

Troubleshooting Method	Applied Layer	Target Issue	Recommended Scenario
--dns-result-order=ipv4first	Node.js Runtime DNS	IPv6 connection hangs & stalls	Home/office networks with broken IPv6 routing
npm config delete proxy	User .npmrc Config	Stale proxy from disconnected VPN	Developers moving between corporate and personal Wi-Fi
Extended --fetch-timeout	CLI Execution Parameter	Slow connections or huge tarballs	High-latency or unstable mobile hotspots
Registry Mirror Fallback	Registry Endpoint	Upstream ISP/CDN peering issues	Temporary public npmjs outage or regional throttling