Error guide

Connection refused (ECONNREFUSED)

The host answered the connection attempt with an explicit rejection — nothing is listening on that port.

Connection refused means the TCP connection attempt reached the host and was actively rejected — the host sent back a reset rather than completing the handshake. It is a fast, definite failure, usually in milliseconds, with no waiting involved.

That speed is diagnostic. The host is up, reachable and processing packets; it simply has nothing listening on that port, or a firewall configured to reject rather than drop. Compare it with a connection timeout, where nothing answers at all and the client waits out its budget.

In practice it nearly always means the process is not running, is listening on a different port, or is bound to an interface that does not include the address being connected to — an application bound to 127.0.0.1 refuses every connection from anywhere else while working perfectly from a shell on the same box.

Common causes

  • The service process is stopped, crashed, or has not finished starting.
  • The process is listening on a different port than the one being connected to.
  • The process is bound to localhost only, refusing external connections.
  • A firewall configured to REJECT rather than DROP traffic on the port.
  • A container port that was never published to the host.
  • A load balancer pointing at a backend port that nothing serves.

How to diagnose it

  1. Check whether the process is running and what it is listening on, with ss or netstat, including the bind address.
  2. Try to connect from the same host as well as from outside: succeeding locally and failing remotely means a bind address or firewall issue.
  3. Check the firewall for explicit reject rules on that port.
  4. For containers, confirm the port is published and the mapping is what you think it is.
  5. Read the service's own startup log — a process that exits immediately leaves the port unbound and looks identical from outside.

Whose fault is it? The server's side

Server-side. The rejection is unambiguous and there is nothing a client can change to get a different answer.

What monitoring sees

A refused connection is a target signal rather than an ambiguous network condition — the host answered, and its answer was no — so Uptimely treats it as a genuine failure rather than as a possible problem with its own network path. The failure threshold still applies: consecutive failed checks declare an incident, a single one does not.

Related error guides

Terms used on this page

Questions

Does connection refused mean the server is down?

The opposite, in one sense: something on the host answered, which means the host is up and reachable. What is down is the service on that port, or the port is not the one the service uses.

Why can I connect locally but not remotely?

Almost always because the process is bound to 127.0.0.1 rather than to all interfaces, or a firewall is rejecting external traffic on that port. Both look identical to a remote client.

One of the Uptimely HTTP and network error guides, written for the person who operates the server rather than the one refreshing the page. Something here read wrong to you? Email support@getuptimely.com.