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.
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
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.
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
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().portto avoid collisions. - Always handle
'error'. An unhandled error event on a socket crashes the process. - Bind to
127.0.0.1for local-only use. Without an address,udp4binds0.0.0.0and 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
recvBufferSizefor 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, seesocket.send().