How to fix Error: ETIMEDOUT in Node.js

Node.jsINTERMEDIATEMEDIUM

This error occurs when a network request does not complete within the specified time limit and the socket connection times out. It commonly happens with HTTP clients when the server takes too long to respond or network connectivity issues prevent timely communication.

What this error means

The ETIMEDOUT error (Error Timeout) is a system-level error code that Node.js raises when a socket operation exceeds its configured timeout period. This typically occurs during outgoing HTTP requests when the remote server fails to respond within the expected timeframe. When you make a network request in Node.js using libraries like axios, node-fetch, or the native http/https modules, a socket connection is established between your application and the remote server. If the server doesn't send data back before the timeout threshold is reached, Node.js terminates the connection and throws an ETIMEDOUT error. This error is distinct from server errors (like 500 Internal Server Error) because the timeout happens at the network/transport layer before any HTTP response is received. It indicates that the TCP connection was established but no data was transmitted within the allowed time window.

How to fix "Error: ETIMEDOUT"

1Configure explicit timeout values

Set appropriate timeout values for your HTTP client. Most libraries use different defaults or no timeout at all.

For axios:

javascript

const axios = require('axios');

const response = await axios.get('https://api.example.com/data', {
  timeout: 10000, // 10 seconds
});

For native fetch (Node.js 18+):

javascript

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000);

try {
  const response = await fetch('https://api.example.com/data', {
    signal: controller.signal
  });
  clearTimeout(timeoutId);
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request timed out');
  }
}

For native http/https modules:

javascript

const https = require('https');

const options = {
  hostname: 'api.example.com',
  path: '/data',
  timeout: 10000 // 10 seconds
};

const req = https.request(options, (res) => {
  // Handle response
});

req.on('timeout', () => {
  req.destroy();
  console.error('Request timed out');
});

req.end();

2Enable HTTP keep-alive for connection pooling

Use persistent connections to reduce connection overhead and prevent socket exhaustion.

For axios:

javascript

const axios = require('axios');
const http = require('http');
const https = require('https');

const httpAgent = new http.Agent({ keepAlive: true });
const httpsAgent = new https.Agent({ keepAlive: true });

const client = axios.create({
  httpAgent,
  httpsAgent,
  timeout: 10000
});

const response = await client.get('https://api.example.com/data');

For native http/https:

javascript

const https = require('https');

const agent = new https.Agent({
  keepAlive: true,
  keepAliveMsecs: 30000,
  maxSockets: 50,
  maxFreeSockets: 10,
  timeout: 10000
});

const options = {
  hostname: 'api.example.com',
  path: '/data',
  agent: agent
};

This reuses existing connections instead of creating new ones for each request.

3Implement retry logic with exponential backoff

Add automatic retries for transient timeout errors to improve reliability.

Using axios-retry:

javascript

const axios = require('axios');
const axiosRetry = require('axios-retry');

axiosRetry(axios, {
  retries: 3,
  retryDelay: axiosRetry.exponentialDelay,
  retryCondition: (error) => {
    return axiosRetry.isNetworkOrIdempotentRequestError(error) ||
           error.code === 'ETIMEDOUT';
  }
});

const response = await axios.get('https://api.example.com/data', {
  timeout: 10000
});

Custom implementation:

javascript

async function fetchWithRetry(url, options = {}, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fetch(url, options);
    } catch (error) {
      if (error.code === 'ETIMEDOUT' && i < maxRetries - 1) {
        const delay = Math.min(1000 * Math.pow(2, i), 10000);
        console.log(`Retry ${i + 1} after ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

4Check and resolve DNS issues

DNS resolution delays can contribute to timeouts. Verify DNS is working properly.

Test DNS resolution:

bash

# Check DNS lookup time
time nslookup api.example.com

# Use dig for more details
dig api.example.com

Configure custom DNS servers in Node.js:

javascript

const dns = require('dns');

// Use Google DNS
dns.setServers(['8.8.8.8', '8.8.4.4']);

// Or Cloudflare DNS
dns.setServers(['1.1.1.1', '1.0.0.1']);

For containerized environments, check /etc/resolv.conf:

bash

cat /etc/resolv.conf

5Monitor and debug socket usage

Track active connections to identify socket exhaustion issues.

Check open sockets:

bash

# View all established connections
netstat -an | grep ESTABLISHED

# Count connections by state
netstat -an | awk '/tcp/ {print $6}' | sort | uniq -c

# Check sockets for specific port
lsof -i :443

Add logging in your application:

javascript

const https = require('https');

const agent = new https.Agent({
  keepAlive: true,
  maxSockets: 50
});

// Log socket statistics
setInterval(() => {
  console.log('Socket stats:', {
    requests: agent.requests,
    sockets: agent.sockets,
    freeSockets: agent.freeSockets
  });
}, 10000);

How to fix Error: ETIMEDOUT in Node.js

What this error means

Typical symptoms

Common causes

How to fix "Error: ETIMEDOUT"

Advanced notes

Related errors

Official resources & further reading