Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns

Node.js net.createConnection() method

Reference for net.createConnection() and net.connect() in Node.js: open TCP or IPC client connections, options, events, timeouts and common errors.

net.createConnection() opens a client connection and returns a net.Socket that is already connecting. net.connect() is an identical alias. Use it for TCP connections (port and host) or for local IPC connections (path).

The connection is asynchronous. The function returns immediately; the 'connect' event fires once the handshake succeeds, and an 'error' event fires if it fails. You can write to the socket right away: data is buffered until the connection is open.

NODE
import net from 'node:net';

const socket = net.createConnection({ port: 3000, host: '127.0.0.1' }, () => {
  socket.write('hello');
});

Try it

Node.js Connect, write, read

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Handling a refused connection

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
net.createConnection(options: object, connectListener?: () => void): net.Socket
net.createConnection(port: number, host?: string, connectListener?: () => void): net.Socket
net.createConnection(path: string, connectListener?: () => void): net.Socket
Name Description
port TCP port to connect to (required for TCP).
host Host name or IP address. Default 'localhost'.
path Unix domain socket path or Windows named pipe. Used instead of port and host.
localAddress, localPort Bind the outgoing side to a specific local address or port.
family 4 or 6 to force an address family; 0 (default) allows both.
timeout Idle timeout in milliseconds. Fires the 'timeout' event; it does not close the socket.
allowHalfOpen Default false. With true, the socket stays open for writing after the other side ends.
noDelay, keepAlive, keepAliveInitialDelay Same meaning as for net.createServer().
autoSelectFamily, autoSelectFamilyAttemptTimeout Try several resolved addresses in turn, see Happy Eyeballs options.
lookup Custom DNS lookup function with the signature of dns.lookup().
signal An AbortSignal that destroys the socket when aborted.
connectListener Added once as a listener for 'connect'.

Returns: a net.Socket.

Errors and edge cases: a missing or out-of-range port throws ERR_SOCKET_BAD_PORT synchronously. Network failures are emitted as 'error': ECONNREFUSED (nothing is listening), ENOTFOUND (the name did not resolve), ETIMEDOUT, ECONNRESET, EHOSTUNREACH.

Usage notes

  • Attach an 'error' listener before anything else. Without one, a refused connection crashes the process.
  • 'connect' fires once. Do not use it as a "ready to read" signal; data events follow independently.
  • timeout only reports. Handle 'timeout' and call socket.destroy() (or end()) yourself.
  • localhost can resolve to ::1 and 127.0.0.1. If the server listens on only one of them, connecting by name can fail unless autoSelectFamily is on (the default since Node 20). Use an explicit IP in tests.
  • Reusing the socket. A closed socket cannot be reconnected reliably; create a new one per connection attempt.
  • Promises. Use await once(socket, 'connect') from node:events; it also rejects if 'error' fires first.
  • Alias. net.connect() and net.createConnection() are the same function; pick one and stay consistent.