write EPIPE / Broken Pipe: Why Writes Fail After the Peer Closes

EPIPE («Broken pipe», errno 32 on Linux) is returned by write(2) when the descriptor «is connected to a pipe or socket whose reading end is closed». The same page notes that the writing process also receives a SIGPIPE signal, which kills it by default; the error code is only seen by programs that catch, block or ignore that signal. Node.js ignores SIGPIPE by default (process docs), so it surfaces as an error event instead:

Error: write EPIPE
    at afterWriteDispatched (node:internal/stream_base_commons)  { errno: -32, code: 'EPIPE', syscall: 'write' }

The Node.js docs describe it as «A write on a pipe, socket, or FIFO for which there is no process to read the data. Commonly encountered at the net and http layers, indicative that the remote side of the stream being written to has been closed.» Python raises BrokenPipeError: [Errno 32] Broken pipe; curl reports a send failure (exit code 55, «Failed sending network data»).

EPIPE and ECONNRESET are two views of the same event. If the peer's reset arrives before your next read, you get ECONNRESET; if your next operation is a write to the already-closed socket, you get EPIPE. Which one appears is a matter of timing.

On the client side, the most common trigger is an upload the server stops reading. The server answers early with an error status and closes; the client is still pushing the body and hits EPIPE before it ever reads that status. Check the server's body limit first, for nginx client_max_body_size, and read the server log for the same timestamp. A response you never saw because of EPIPE is often a plain 413.

On the server side, EPIPE while writing a response usually means the client left: closed the tab, hit a timeout, or a proxy gave up first. That is normal traffic, not a bug, but an unhandled 'error' event on the stream still crashes a Node.js process. Listen for it and stop producing data:

res.on('close', () => { stream.destroy(); });
stream.on('error', (err) => {
  if (err.code === 'EPIPE' || err.code === 'ECONNRESET') return; // client went away
  console.error(err);
});
stream.pipe(res);

When this happens at a fixed duration on long requests, a proxy in front is closing the connection; see upstream prematurely closed connection for the nginx side.

Command-line tools hit EPIPE when their output is piped into a program that stops reading early. node list.js | head -n 5 works until head exits after line five; the next write to stdout fails. Shell tools written in C are simply killed by SIGPIPE, which is why yes | head exits quietly. In Node.js, end the process cleanly instead of printing a stack trace:

process.stdout.on('error', (err) => {
  if (err.code === 'EPIPE') process.exit(0);
  throw err;
});

1. Identify the stream. The stack trace tells you whether the write was to an HTTP request body, a response, a database socket or stdout.
2. For uploads, read the server's verdict. Send the same request with curl and watch for an early response:

   curl -v -T big.bin https://api.example.com/upload
   # < HTTP/1.1 413 Request Entity Too Large

3. Check idle and request timeouts on every hop (load balancer, nginx proxy_read_timeout, the app server) and keep the upstream one longer.
4. Validate pooled connections before use, or lower the pool's idle timeout below the server's.
5. Handle the error event on every stream you write to, and stop writing once 'close' has fired.

curl -sS -o /dev/null -w '%{http_code}\n' -T big.bin https://api.example.com/upload
# 201

Then check application logs over a normal day: EPIPE from clients that disconnect will still occur occasionally and should be logged at debug level, not as crashes. The HTTP status checker shows the status code and headers a URL returns.

• ECONNRESET — the same close, noticed on read
• ETIMEDOUT — the peer stopped acknowledging data
• upstream prematurely closed connection — the nginx view of a closed upstream
• ERR_CONNECTION_RESET — what a browser shows for a reset