A Transform error in Node.js is not the end of the debugging story. You also need to know what happened to the Readable before it and the Writable after it. A chain can report an error while still leaving connected streams open.
Prerequisites: familiarity with a Readable → Transform → Writable flow, object-mode streams, and asynchronous error handling. The inserted example uses a small in-memory source, a Transform that uppercases values, and a destination that captures output. One chosen value causes the Transform to fail, making the lifecycle outcome easy to inspect.
The implementation decision is whether to join stages with repeated .pipe() calls or use stream.pipeline(). With .pipe(), attach an error listener if you need to observe the Transform failure. That prevents the error from going unhandled, but it does not automatically destroy the source or finish and close the destination. The chain may retain partial output, an unread source, and a Writable that has not completed.
For a job where every stage should stop together, make pipeline() the application-facing boundary. Give it the source, Transform, and destination, then handle its rejection. When the Transform fails, the operation reports the error and coordinates cleanup across the connected stages. If no value triggers the failure, every transformed value reaches the destination and the destination finishes.
Expected result: after the failing run, compare the received output with stream state. The Transform is the failing stage, but with pipeline() the source and destination should also be part of the teardown. With .pipe() alone, they can remain open unless your own error path explicitly closes them.
One limitation matters: this is a lifecycle demonstration, not a performance test or a guarantee about every file, socket, or third-party stream. Manual .pipe() teardown can be correct, but it requires the same care for all participants and every failure path.
Working example
import { Readable, Transform, Writable } from 'node:stream';
import { pipeline } from 'node:stream/promises';
function makeChain(chunks, failOn) {
let index = 0;
const received = [];
// A one-item high-water mark prevents this source from eagerly ending before
// the transform gets a chance to reject a later item.
const source = new Readable({
objectMode: true,
highWaterMark: 1,
read() {
if (index === chunks.length) {
this.push(null);
return;
}
this.push(chunks[index++]);
},
});
const transformer = new Transform({
objectMode: true,
highWaterMark: 1,
transform(chunk, _encoding, callback) {
if (chunk === failOn) {
callback(new Error(`transform rejected: ${String(failOn)}`));
return;
}
callback(null, String(chunk).toUpperCase());
},
});
const destination = new Writable({
objectMode: true,
write(chunk, _encoding, callback) {
received.push(chunk);
callback();
},
});
return { source, transformer, destination, received };
}
function state(chain) {
return {
output: chain.received,
sourceDestroyed: chain.source.destroyed,
sourceEnded: chain.source.readableEnded,
transformDestroyed: chain.transformer.destroyed,
destinationDestroyed: chain.destination.destroyed,
destinationFinished: chain.destination.writableFinished,
};
}
// This deliberately uses ordinary .pipe(). Its error listener prevents an
// unhandled-error crash, but it does not implement cleanup for the other ends.
export async function processWithPipe(chunks, failOn) {
const chain = makeChain(chunks, failOn);
const error = await new Promise((resolve) => {
chain.transformer.once('error', resolve);
chain.source.pipe(chain.transformer).pipe(chain.destination);
});
return { error, ...state(chain) };
}
// This is the application-facing alternative for a connected stream chain.
export async function processWithPipeline(chunks, failOn) {
const chain = makeChain(chunks, failOn);
let error = null;
try {
await pipeline(chain.source, chain.transformer, chain.destination);
} catch (caught) {
error = caught;
}
return { error, ...state(chain) };
}
Read the full article: https://chriseugenerodriguez.com/blog/why-does-pipe-leave-a-failed-node-stream-chain-open