Cara mengatasi ETIMEDOUT Node.js paling cepat adalah menaikkan timeout client, lalu memastikan target server, DNS, dan firewall bisa dijangkau. Error ini berarti Node.js sudah membuka koneksi tapi tidak mendapat respons dalam batas waktu, bukan selalu server mati. Cek dulu durasi request, host tujuan, dan log error sebelum mengubah kode.
Penyebab Umum ETIMEDOUT di Node.js
ETIMEDOUT muncul di fetch, axios, http.request, koneksi database, atau panggilan API eksternal. Pola kegagalannya memberi petunjuk besar tentang sumber masalah.
- Server tujuan lambat atau overload sehingga respons melebihi timeout bawaan.
- DNS gagal resolve atau routing salah, biasanya hanya ke satu host.
- Firewall, security group, atau IP allowlist memblokir koneksi keluar.
- Timeout client terlalu pendek, misalnya 5 detik untuk API berat.
- Koneksi database idle terlalu lama lalu diputus pool atau NAT.
Cek cepat sebelum perbaikan: salin pesan error lengkap, catat waktu respons, uji DNS, pastikan port tujuan terbuka, dan periksa limit koneksi server.
Tabel Diagnosis Cepat ETIMEDOUT
Validasi dengan timeout lebih panjang dan uji koneksi ulang dahulu. Jangan langsung refactor kode.
| Gejala | Kemungkinan Penyebab | Cek Awal |
|---|---|---|
| Selalu gagal sekitar 5 detik | Timeout client terlalu pendek | Naikkan ke 15-30 detik lalu uji ulang |
| Hanya gagal ke satu host | DNS atau firewall tujuan | Uji DNS lookup dan koneksi TCP |
| Error acak saat traffic naik | Server overload atau pool habis | Periksa latensi, antrian, dan pool |
Langkah Memperbaiki ETIMEDOUT dengan Kode Minimal
- Tambah timeout eksplisit pada setiap request eksternal.
- Pasang
try/catchagar ETIMEDOUT tidak menghentikan proses. - Batasi retry maksimal 2-3 kali dengan backoff, misalnya 500ms lalu 2 detik.
- Gunakan
AbortControlleragar request lama bisa dibatalkan bersih.
// Node.js 18+
try {
const res = await fetch(process.env.API_URL, {
signal: AbortSignal.timeout(15000)
});
const data = await res.json();
} catch (err) {
console.error(err.code || err.name);
}
const axios = require('axios');
try {
const res = await axios.get(process.env.API_URL, {
timeout: 15000
});
} catch (err) {
console.error(err.code);
}
Jangan retry tanpa batas karena bisa membanjiri API. Jangan mencatat token, API key, atau secret ke log error.
FAQ
Apakah ETIMEDOUT selalu berarti server down?
Tidak. Penyebab umum justru respons lambat, jaringan terblokir, atau timeout client terlalu singkat.
Berapa nilai timeout yang aman untuk API eksternal?
Umumnya 10-30 detik untuk API eksternal, lebih pendek untuk API internal yang cepat.
Kapan perlu retry request yang ETIMEDOUT?
Retry hanya untuk operasi idempoten seperti GET, maksimal 2-3 kali dengan jeda bertambah.