Understanding Node.js ETIMEDOUT, EADDRINUSE and Other Socket Errors

1. Introduction

Anyone familiar with Node.js has probably seen errors such as ETIMEDOUT, EADDRINUSE, etc. These messages originate from the glibc library, which Node.js uses for low‑level socket operations. While V8 may add some custom errors, most correspond to glibc definitions.

The connect function is defined as:

int connect(int socket, struct sockaddr *addr, socklen_t length)

connect

uses the file descriptor socket to initiate a connection to the address specified by addr and length. Typically the socket refers to a remote server that must already be listening.

In normal operation connect blocks until the server responds. The socket can be set to non‑blocking mode to return immediately, as done by servers like nginx.

2. Error Types

The connect function returns 0 on success and –1 on error, setting errno to one of the following values:

EBADF : socket is not a valid file descriptor.

ENOTSOCK : the file descriptor does not refer to a socket.

EADDRNOTAVAIL : the specified address is unavailable on the remote machine.

EAFNOSUPPORT : the socket does not support the address family of addr .

EISCONN : the socket is already connected.

ETIMEDOUT : the connection attempt timed out.

ECONNREFUSED : the server actively refused the connection.

ENETUNREACH : the network to the given addr is unreachable.

EADDRINUSE : the address is already in use (commonly seen when a port is occupied by another Node.js process).

EINPROGRESS : the socket is non‑blocking and the connection cannot be completed immediately; select can be used to wait for completion. If connect is called again before the connection finishes, it fails with EALREADY .

EALREADY : the socket is non‑blocking and a connection attempt is already pending.

3. Notes

connect

is defined as a cancellation point in multithreaded programs; developers must ensure that resources such as memory, file descriptors, and semaphores are released after thread cancellation.

References

libc: Making a Connection

Socket address resolution

File status flags