Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

A Node.js script crashes with write EPIPE when its output is piped to head

ErrorError: write EPIPE

Short answer

EPIPE means your script wrote to a pipe or socket after the reader had closed it, for example when head has printed enough lines and exits. Node.js turns that into an error event on process.stdout. If nothing listens, the process crashes. Add an error listener that treats EPIPE as a normal end.

  • Applies to Node.js 22, Node.js 24, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the script with and without the pipe. If it only fails when a reader such as head closes early, the cause is the first one below. If the failing stream is a socket or an HTTP response, see the second.

    node script.js > /dev/null; echo "exit: $?"
    node script.js | head -n 1; echo "exit: ${PIPESTATUS[0]}"
  2. 2Match what you see, then jump to its fix

    1. 1Error: write EPIPE, only when the output goes to head, sed -n 1q, a pager or another program that quits earlyThe program on the right of the pipe exited before your script finished writingFix
    2. 2write EPIPE with a stack through net or http, not tied to a shell pipeYou write to a socket or response whose other side has closedFix

What does the error look like?

  • Error: write EPIPE
  • code: 'EPIPE'

Cause 1 of 2

The program on the right of the pipe exited before your script finished writing

1Check

Node.js docs list EPIPE as a write on a pipe with no process left to read the data. On POSIX systems, writes to a pipe on process.stdout are asynchronous, and SIGPIPE is ignored by default, so the failure arrives as an error event on process.stdout, not as a silent kill.

node -e "for (let i = 0; i < 1e6; i++) console.log(i)" | head -n 1

2Fix

Listen for the error event on process.stdout. Exit quietly on EPIPE, because nobody wants the rest of the output, and rethrow anything else.

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

3Verify

Run the same pipe again. The output should be one line and no stack trace.

node script.js | head -n 1

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 2

You write to a socket or response whose other side has closed

1Check

The Node.js error documentation says EPIPE is common at the net and http layers and means the remote side of the stream has been closed. Find the write that runs after the peer disconnected, for example a loop that keeps writing to a response after the client left.

node script.js 2>&1 | head -n 20

2Fix

Attach an error listener to that stream. An EventEmitter that emits error with no listener throws and ends the process. For piped data, use stream.pipeline from node:stream/promises, which rejects with the error so you can catch it.

const { pipeline } = require('node:stream/promises');

async function run(source, destination) {
  try {
    await pipeline(source, destination);
  } catch (err) {
    if (err.code !== 'EPIPE') throw err;
  }
}

3Verify

Close the client mid-transfer and confirm the process stays up and the catch block runs.

node script.js

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Put an error listener on every stream you create or receive, not only on the happy path.
  • Use stream.pipeline instead of chaining pipe calls by hand, so one failure reaches one place.
  • For command-line tools that print a lot, treat EPIPE on stdout as a normal way to finish.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.