Skip to content
Back to the playbook

Diagnosing Node.js ECONNREFUSED

Node.jsrevision 1

Diagnostic tree

  1. In progressNode process throws ECONNREFUSEDECONNREFUSED means the TCP handshake reached the target host and was actively rejected (an RST) — nothing is listening on that exact port there right now. This narrows the cause to three things: nothing's listening yet, the app is connecting to the wrong host/port, or the thing that should be listening crashed.
View the whole map (7 more steps)
  • Is anything currently listening at that exact host and port?
  • Something is listening there right now
  • Does the app's configured address actually match where the dependency lives?
  • Root cause: wrong host/port for where the dependency actually runs
  • Did the dependency actually finish starting, or has it crashed?
  • Root cause: startup-order race
  • Dependency believes it's listening but still refuses this app

What to test

Node process throws ECONNREFUSED

ECONNREFUSED means the TCP handshake reached the target host and was actively rejected (an RST) — nothing is listening on that exact port there right now. This narrows the cause to three things: nothing's listening yet, the app is connecting to the wrong host/port, or the thing that should be listening crashed.

What happened?

Passed