Skip to content
Tutorials Center
My learning

Topics

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

Node.js dgram.createSocket() method

Reference for dgram.createSocket() in Node.js: create UDP sockets, bind to a port, receive datagrams with the message event, and handle options, errors and close.

dgram.createSocket() creates a UDP socket. UDP is connectionless: there is no handshake, no stream and no delivery guarantee. Each send() produces one self-contained datagram, and each 'message' event delivers exactly one datagram, with boundaries preserved. Datagrams may be lost, duplicated or arrive in a different order, so protocols built on UDP (DNS, game networking, service discovery, QUIC) add their own reliability where needed.

The returned dgram.Socket is an EventEmitter, not a stream. It can send before it is bound (the system then picks a random port), but to receive you must call bind() so other programs know where to send.

NODE
import dgram from 'node:dgram';

const socket = dgram.createSocket('udp4');
socket.on('message', (message, remote) => console.log(message.toString(), remote.port));
socket.bind(41234);

Try it

Node.js A receiver and a sender

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 Port conflicts and reuseAddr

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
dgram.createSocket(type: 'udp4' | 'udp6', callback?: (message: Buffer, remote: RemoteInfo) => void): dgram.Socket
dgram.createSocket(options: object, callback?): dgram.Socket
socket.bind(port?: number, address?: string, callback?: () => void): dgram.Socket
socket.bind(options: { port, address, exclusive, fd }, callback?): dgram.Socket
socket.close(callback?: () => void): void
socket.address(): { address: string, family: string, port: number }
Name Description
type 'udp4' or 'udp6' (required).
reuseAddr Allow several sockets to bind the same address and port. Default false.
reusePort Allow load-balancing across processes on Linux (Node 23.1 and later).
ipv6Only For udp6 sockets, disable dual-stack so only IPv6 is used.
recvBufferSize, sendBufferSize Sizes of the kernel buffers in bytes.
lookup Custom DNS lookup used when send() receives a host name.
signal An AbortSignal that closes the socket.
callback Added as a listener for 'message'.

Events: 'message' (message as a Buffer, remote with address, family, port, size), 'listening', 'close', 'error', 'connect'.

Errors and edge cases: an invalid type throws ERR_SOCKET_BAD_TYPE. Binding an occupied port emits 'error' with EADDRINUSE. Calling bind() twice throws ERR_SOCKET_ALREADY_BOUND; using a closed socket throws ERR_SOCKET_DGRAM_NOT_RUNNING.

Usage notes

  • Port 0 for tests. Bind to port 0 and read address().port to avoid collisions.
  • Always handle 'error'. An unhandled error event on a socket crashes the process.
  • Bind to 127.0.0.1 for local-only use. Without an address, udp4 binds 0.0.0.0 and accepts packets from every interface.
  • Message size. One datagram can carry up to 65,507 bytes of payload over IPv4, but anything above the network MTU (about 1,472 bytes on Ethernet) is fragmented and more likely to be lost. Keep messages small.
  • Sockets keep the process alive until closed, or until you call socket.unref().
  • Receive buffers overflow silently. A slow consumer loses datagrams. Increase recvBufferSize for bursts, and never assume you saw every packet.
  • Same-host speed is not a guarantee. Loopback rarely drops packets, but the protocol must still tolerate loss on real networks.
  • Use a connected socket (socket.connect()) when talking to one peer, see socket.send().