Skip to content
Tutorials Center
My learning

Topics

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

The Node.js net.Server class

Reference for net.Server in Node.js: listen options, address(), close(), getConnections(), maxConnections and the listening, connection, close and error events.

net.Server is the object returned by net.createServer(). It listens on a TCP port or an IPC path and emits a 'connection' event with a net.Socket for every client. It is an EventEmitter, and the HTTP, HTTPS and TLS servers are all built on top of it.

A server has a simple life cycle: created, listening, closed. listen() binds the port and starts the 'listening' event; close() stops accepting new connections and emits 'close' once the last existing connection has ended.

NODE
import net from 'node:net';

const server = net.createServer();
server.on('connection', (socket) => socket.end('bye\n'));
server.listen({ port: 0, host: '127.0.0.1' });

Try it

Node.js Life cycle events and address()

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 maxConnections and the EADDRINUSE error

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
class net.Server extends EventEmitter
server.listen(port?: number, host?: string, backlog?: number, callback?: () => void): net.Server
server.listen(options: { port, host, path, backlog, exclusive, ipv6Only, signal, reusePort }, callback?): net.Server
server.listen(path: string, callback?): net.Server
server.close(callback?: (error?: Error) => void): net.Server
server.address(): { address: string, family: string, port: number } | string | null
server.getConnections(callback: (error: Error | null, count: number) => void): net.Server
Member Description
listen(...) Starts listening. Port 0 picks a free port. Without host, binds :: when IPv6 is available, otherwise 0.0.0.0. Calling it on an already listening server throws ERR_SERVER_ALREADY_LISTEN.
close(callback) Stops accepting connections. The callback runs after 'close', and receives an error if the server was not open (ERR_SERVER_NOT_RUNNING).
address() An object for TCP, a string for pipes, null if not listening.
getConnections(cb) Asynchronously counts open connections.
maxConnections Connections beyond this limit are dropped and 'drop' is emitted.
listening true while the server is listening.
ref(), unref() Whether the server keeps the process alive.
[Symbol.asyncDispose]() Closes the server with await using.

Events: 'listening', 'connection' (socket), 'close', 'error', 'drop' (data about a connection refused because of maxConnections).

Errors and edge cases: common listen errors are EADDRINUSE (port taken), EACCES (privileged port), EADDRNOTAVAIL (address not on this machine). They are emitted as 'error', not thrown.

Usage notes

  • Wait for 'listening'. listen() returns immediately; read address() only after the event (or in the callback).
  • close() waits. A keep-alive client holds the server open. Track sockets and destroy() them if shutdown must be quick.
  • address() after close() is null. Save the port first if you need it later.
  • Pipes return strings. For IPC servers address() returns the path, not an object.
  • exclusive and clusters. In a cluster worker, listen() shares the handle with the primary unless exclusive: true.
  • Port 0 for tests. It avoids clashes between parallel test runs.
  • Use unref() for helper servers that should not keep a process alive on their own.