Error ECONNREFUSED di Node.js berarti aplikasi mencoba membuka koneksi TCP, tetapi tidak ada proses yang menerima koneksi di host dan port itu. Perbaiki tercepat: pastikan server tujuan sudah berjalan, lalu samakan HOST dan PORT di client dengan server yang aktif.
Penyebab ECONNREFUSED Paling Sering di Node JS
Node.js menampilkan error ini lewat fetch, http.request, driver database, atau Redis client. Pesan lengkap biasanya menyebut alamat seperti 127.0.0.1:3000.
- Server tujuan belum berjalan atau crash. Express belum di-
listen, proses berhenti, atau PM2/Docker restart gagal. - Port, host, dan URL koneksi salah ketik. Client menembak port 3000, server jalan di 5000.
- Firewall, bind address, dan backlog koneksi. Server hanya listen di
127.0.0.1tetapi diakses lewat IP LAN, atau port diblokir firewall VPS. - Koneksi MySQL, PostgreSQL, Redis ditolak. Service database mati, kredensial salah, atau konfigurasi host memakai
localhostpadahal database di container lain.
Tabel Diagnosis Cepat ECONNREFUSED
| Gejala | Penyebab | Cek Awal |
|---|---|---|
Gagal ke localhost:3000 |
Express belum listen | Cek log app.listen dan proses Node |
| Gagal ke API eksternal | URL atau port salah | Uji URL dengan curl |
| Gagal ke MySQL/PostgreSQL/Redis | Service mati atau host salah | Cek status service dan variabel DB_HOST |
Cara Memperbaiki ECONNREFUSED Langkah per Langkah
- Baca pesan error lengkap dan port target. Catat alamat di
error.addressdanerror.portlewat log. - Pastikan server Express dan database aktif. Periksa terminal server, Docker, atau status service database sebelum mengubah kode.
- Perbaiki
PORT,HOST, danDB_HOSTlewatprocess.env. Jangan hardcode alamat berbeda antara development dan production. - Uji koneksi dengan
curldan kodefetch/httpminimal. Contoh uji cepat:
curl -v http://127.0.0.1:3000/health
node -e "fetch('http://127.0.0.1:3000/health').then(r=>console.log(r.status)).catch(console.error)"
Jika curl berhasil tetapi Node.js gagal, masalah ada di konfigurasi URL dalam kode. Jika keduanya gagal, server memang belum menerima koneksi.
- Atasi retry aman tanpa loop tanpa batas. Batasi percobaan, beri jeda, dan hentikan saat error berulang:
async function connectWithRetry(fn, maxRetry = 5) {
for (let i = 1; i <= maxRetry; i++) {
try {
return await fn();
} catch (err) {
if (err.code !== 'ECONNREFUSED' || i === maxRetry) throw err;
await new Promise(r => setTimeout(r, 1000 * i));
}
}
}
FAQ
Kenapa ECONNREFUSED hanya terjadi ke database?
Service database belum jalan atau DB_HOST menunjuk host yang salah, periksa status MySQL, PostgreSQL, atau Redis terlebih dahulu.
Apakah mematikan firewall solusi yang benar?
Tidak, buka hanya port yang dibutuhkan dan batasi akses database ke IP aplikasi.
Kapan memakai 127.0.0.1 dibanding localhost?
Gunakan 127.0.0.1 bila resolusi localhost bermasalah ke IPv6, terutama di Docker atau Windows.