denoland/deno · error · SystemError

ERR_SOCKET_BUFFER_SIZE

ERR_SOCKET_BUFFER_SIZE

Error message

Could not get or set buffer size: ${context.syscall} returned ${context.code} (${context.message})

What it means

After the uint32 check passes, bufferSize() delegates to the native handle; if the OS-level getsockopt/setsockopt syscall fails, the handle returns undefined and the error context (syscall, code/errno, message) captured in ctx is wrapped in ERR_SOCKET_BUFFER_SIZE. This is a runtime failure of the socket option itself, not an argument problem.

Source

Thrown at ext/node/polyfills/dgram.ts:1410

  newHandle.bind = oldHandle.bind;
  newHandle.send = oldHandle.send;
  newHandle[ownerSymbol] = self;

  // Replace the existing handle by the handle we got from primary.
  oldHandle.close();
  state.handle = newHandle;
}

function bufferSize(self: Socket, size: number, buffer: boolean): number {
  if (size >>> 0 !== size) {
    throw new ERR_SOCKET_BAD_BUFFER_SIZE();
  }

  const ctx = {};
  const ret = self[kStateSymbol].handle!.bufferSize(size, buffer, ctx);

  if (ret === undefined) {
    throw new ERR_SOCKET_BUFFER_SIZE(ctx as NodeSystemErrorCtx);
  }

  return ret;
}

function socketCloseNT(self: Socket) {
  self.emit("close");
}

function healthCheck(socket: Socket) {
  if (!socket[kStateSymbol].handle) {
    // Error message from dgram_legacy.js.
    throw new ERR_SOCKET_DGRAM_NOT_RUNNING();
  }
}

function stopReceiving(socket: Socket) {
  const state = socket[kStateSymbol];

View on GitHub (pinned to 89f33cbef2)

Solutions

1. Lower the requested size (start at 1-4 MiB and binary-search the maximum the OS accepts)
2. On Linux raise the caps: sysctl -w net.core.rmem_max=<n> and net.core.wmem_max=<n> (needs privileges)
3. Wrap the call in try-catch and continue with the OS default buffer size, logging the syscall/errno from the error context

Example fix

// before
sock.setRecvBufferSize(64 * 1024 * 1024); // may throw ERR_SOCKET_BUFFER_SIZE (setsockopt)

// after
try {
  sock.setRecvBufferSize(4 * 1024 * 1024);
} catch (err) {
  if (err.code === 'ERR_SOCKET_BUFFER_SIZE') {
    console.warn(`buffer size rejected (${err.syscall} ${err.code}): keeping OS default`);
  } else throw err;
}

// Probe the maximum acceptable size once at startup, then reuse it
function probeMaxBuffer(sock, start, max) {
  let ok = 0;
  for (let s = start; s <= max; s *= 2) {
    try { sock.setRecvBufferSize(s); ok = s; } catch { return ok; }
  }
  return ok;
}

try {
  sock.setRecvBufferSize(want);
} catch (err) {
  if (err?.code === 'ERR_SOCKET_BUFFER_SIZE') {
    // err.syscall/err.code/err.message carry the failing getsockopt/setsockopt context
    log.warn('kernel rejected buffer size, keeping default', err.syscall, err.errno);
  } else throw err;
}

When it happens

Trigger: socket.setRecvBufferSize(64 * 1024 * 1024) on Linux where net.core.rmem_max is far lower; setSendBufferSize with a size the kernel rejects; querying buffer sizes on a socket whose handle hit a resource limit.

Common situations: High-throughput UDP apps (media streaming, telemetry) requesting OS buffers larger than kernel defaults; containers with locked-down sysctls; macOS where buffer clamping differs from Linux.

Related errors

• ERR_SOCKET_BAD_BUFFER_SIZE
• ERR_SOCKET_DGRAM_NOT_RUNNING
• ERR_MISSING_ARGS
• ERR_SOCKET_ALREADY_BOUND
• ERR_INVALID_FD_TYPE

AI-assisted analysis of denoland/deno@89f33cbef2 (2026-08-16). Data as JSON: /api/errors/29c676f1dba072f0. Report an issue: GitHub.