EC
ETOOMANYREFS
Linux / POSIXERRORCriticalNetworkHIGH confidence

Too Many References: Cannot Splice

Production Risk

Rare; only occurs when sending large numbers of fds via Unix sockets.

What this means

ETOOMANYREFS (errno 109) is returned when too many references exist to a socket for it to be spliced. This relates to the sending of file descriptors over Unix domain sockets using SCM_RIGHTS.

Why it happens
  1. 1Sending too many file descriptors in SCM_RIGHTS across a Unix socket
  2. 2Internal kernel reference count overflow for a socket
How to reproduce

sendmsg() with too many SCM_RIGHTS fds.

trigger — this will error
trigger — this will error
// Sending too many fds via SCM_RIGHTS
struct msghdr msg = { ... };
// cmsg with 1024 fds — exceeds limit
sendmsg(sockfd, &msg, 0);
// Returns -1, errno = ETOOMANYREFS

expected output

sendmsg: Too many references: cannot splice (ETOOMANYREFS)

Fix

Batch fd transfers into smaller groups

WHEN When sending many fds via SCM_RIGHTS

Batch fd transfers into smaller groups
// Send fds in batches of ≤ 253 (kernel limit)
// The kernel limit for SCM_RIGHTS per sendmsg is SCM_MAX_FD (253)
#include <sys/socket.h>
// SCM_MAX_FD == 253 on Linux
for (int i = 0; i < total_fds; i += SCM_MAX_FD) {
  // send batch of min(SCM_MAX_FD, remaining) fds
}

Why this works

Linux limits SCM_RIGHTS to SCM_MAX_FD (253) file descriptors per sendmsg call.

Sources
Official documentation ↗

Linux Programmer Manual unix(7)

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Linux / POSIX errors