A Node.js script crashes with write EPIPE when its output is piped to head
Error: write EPIPEShort 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.
Fix it fast
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]}"2Match what you see, then jump to its fix
- 1
Error: 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
write 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
- 1
What does the error look like?
Error: write EPIPEcode: '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 12Fix
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 1Confirmed by nodejs.org
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 202Fix
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.jsConfirmed by nodejs.org
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
Back end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fixBack end
corepack enable fails: permission denied while creating the pnpm link
Internal Error: EACCES: permission denied, symlink '../lib/node_modules/corepack/dist/pnpm.js' -> '/usr/local/bin/pnpm'
corepack enable writes small link files for yarn and pnpm next to your node binary.
2 causes, each with a fixBack end
Create React App says Node is too old, and npm will not run on the new one
npm does not support Node.js v10.19.0
The shell is running an old Node.js that is below the version Create React App needs.
3 causes, each with a fixBack end
firebase deploy cannot load your functions: user code failed to load
Functions codebase could not be analyzed successfully. It may have a syntax or runtime error
The Firebase CLI loads your functions code on your machine before it deploys, to learn which functions exist.
4 causes, each with a fixBack end
firebase deploy stops because the predeploy lint step failed
Error: There was an error deploying functions
The predeploy hook in firebase.json runs npm run lint before every deploy, and a failing hook cancels the deploy.
3 causes, each with a fixBack end
fluent-ffmpeg cannot find the ffmpeg or ffprobe binary
Error: Cannot find ffprobe
fluent-ffmpeg does not bundle ffmpeg.
4 causes, each with a fix