How to fix Error: Transform stream callback not called (transform not pushed data) in Node.js
This error occurs when a Node.js Transform stream's _transform() method fails to call its callback function, or when the stream callback is invoked without data being pushed to the output buffer. It causes the stream to hang indefinitely, stopping all further data processing through the pipeline.
Quick fix
Fixes Error: Transform stream callback not called (transform not pushed data)
const { Transform } = require('stream');
const transformStream = new Transform({
transform(chunk, encoding, callback) {
try {
const result = processData(chunk);
// Option 1: Pass data directly to callback
callback(null, result);
} catch (err) {
// Always pass errors to callback
callback(err);
}
}
});
// Usage
sourceStream.pipe(transformStream).pipe(destinationStream);- Ensure callback is always called exactly once
- Call callback in all code paths, especially in async code
- Use callback pattern correctly with this.push()
- Handle errors properly and avoid losing callback references
const { Transform } = require('stream');const transformStream = new Transform({transform(chunk, encoding, callback) {try {const result = processData(chunk);// Option 1: Pass data directly to callbackcallback(null, result);} catch (err) {// Always pass errors to callbackcallback(err);}}});// UsagesourceStream.pipe(transformStream).pipe(destinationStream);Error: Transform stream callback not called (transform not pushed data)
What this error means
A Transform stream callback error indicates that the _transform() method did not properly invoke its callback function or did not push any data to the stream output before completing. Transform streams are bidirectional: they accept input data, transform it, and output results through a callback mechanism. When the _transform() method is invoked with a chunk of data, you must either: 1. Call callback(null, transformedData) to pass transformed data downstream 2. Call this.push(transformedData) followed by callback() 3. Call callback() if the chunk produces no output (filtering) Failing to call the callback prevents the stream from processing the next chunk. The stream becomes stuck waiting for the callback, causing the entire pipeline to stall. This is a critical runtime error that breaks data flow through the stream chain. This error commonly occurs when callbacks are forgotten in asynchronous operations, when errors aren't properly passed to callbacks, or when developers misunderstand the required callback-driven architecture of Transform streams.
Typical symptoms
- Stream stops processing indefinitely without completing
- No error is thrown, but pipeline hangs or times out
- Data enters the stream but never exits or gets processed
- Memory usage increases as buffered data accumulates
- Process appears frozen when piping through transform streams
- Dependent streams never receive "end" or "finish" events
- Callback-based code in _transform() is never completed
- Async operations in transform complete but callback isn't called
Common causes
- Callback function is not called at all in _transform() method
- Async operation completes but callback is not invoked in the promise resolution
- Error in _transform() is thrown but not passed to callback(error)
- Conditional logic exits _transform() without calling callback
- Data is pushed but callback is never called afterward
- Multiple conditional paths in _transform() don't all call callback
- Callback is called in wrong scope or lost due to this binding
- Forget to call callback() after calling this.push() in synchronous code
How to fix "Error: Transform stream callback not called (transform not pushed data)"
The callback must be called exactly once per _transform() invocation. Use this pattern:
const { Transform } = require('stream');
const transformStream = new Transform({
transform(chunk, encoding, callback) {
try {
const result = processData(chunk);
// Option 1: Pass data directly to callback
callback(null, result);
} catch (err) {
// Always pass errors to callback
callback(err);
}
}
});
// Usage
sourceStream.pipe(transformStream).pipe(destinationStream);The callback must be called exactly once. If you call it twice, you'll get "Callback was already called" errors. If you don't call it at all, the stream hangs.
When using async operations, ensure callback is called in both success and error paths:
const { Transform } = require('stream');
const transformStream = new Transform({
async transform(chunk, encoding, callback) {
try {
// Async operation
const result = await fetchAndProcess(chunk);
callback(null, result);
} catch (err) {
// CRITICAL: Pass error to callback
callback(err);
}
}
});
// Example with Promise
const transformStream2 = new Transform({
transform(chunk, encoding, callback) {
asyncOperation(chunk)
.then(result => {
callback(null, result); // Call on success
})
.catch(err => {
callback(err); // Call with error
});
}
});Never forget the error path. Even if you expect no errors, always include .catch() or error handling.
There are two valid patterns for outputting data. Choose one consistently:
const { Transform } = require('stream');
// Pattern 1: Pass data to callback (recommended)
const transform1 = new Transform({
transform(chunk, encoding, callback) {
const result = processData(chunk);
callback(null, result); // Data goes directly to callback
}
});
// Pattern 2: Use this.push() then call callback
const transform2 = new Transform({
transform(chunk, encoding, callback) {
const result = processData(chunk);
this.push(result);
callback(); // Signal chunk processing is complete
}
});
// Pattern 3: Multiple pushes with one callback
const transform3 = new Transform({
transform(chunk, encoding, callback) {
// Can push multiple times
this.push('prefix_' + chunk);
this.push('_suffix');
// But callback is called once
callback();
}
});
// Pattern 4: Filter out data (no push, but still callback)
const filterTransform = new Transform({
transform(chunk, encoding, callback) {
if (shouldKeep(chunk)) {
callback(null, chunk);
} else {
callback(); // Don't output this chunk
}
}
});Pick one approach and stick with it consistently throughout your transform method.
Errors in _transform() must be passed to the callback, not thrown:
const { Transform } = require('stream');
// WRONG: Throwing an error breaks the stream
const badTransform = new Transform({
transform(chunk, encoding, callback) {
if (chunk.length === 0) {
throw new Error('Empty chunk'); // Bad: stream breaks
}
callback(null, chunk.toUpperCase());
}
});
// CORRECT: Pass errors to callback
const goodTransform = new Transform({
transform(chunk, encoding, callback) {
if (chunk.length === 0) {
// Good: error is handled by callback
return callback(new Error('Empty chunk'));
}
callback(null, chunk.toUpperCase());
}
});
// CORRECT: Use try-catch to capture and pass errors
const safeTransform = new Transform({
transform(chunk, encoding, callback) {
try {
const result = riskyOperation(chunk);
callback(null, result);
} catch (err) {
callback(err); // Pass the error
}
}
});
// Listen for error events
goodTransform.on('error', (err) => {
console.error('Transform error:', err.message);
});Always pass errors to the callback, never throw them. Thrown errors will not be caught by stream error handlers.
Be careful with this binding and callback references in nested contexts:
const { Transform } = require('stream');
// WRONG: 'this' binding is lost in callback
const badTransform = new Transform({
transform(chunk, encoding, callback) {
setTimeout(() => {
// 'this' is undefined here
this.push(processData(chunk)); // Error: this is undefined
callback();
}, 100);
}
});
// CORRECT: Preserve 'this' with arrow functions or bind()
const goodTransform = new Transform({
transform(chunk, encoding, callback) {
// Arrow function preserves 'this'
setTimeout(() => {
this.push(processData(chunk)); // 'this' is the Transform
callback();
}, 100);
}
});
// CORRECT: Use bind() with regular functions
const altTransform = new Transform({
transform: function(chunk, encoding, callback) {
setTimeout(function() {
this.push(processData(chunk));
callback();
}.bind(this), 100);
}
});
// CORRECT: Store reference outside callback
const storeRefTransform = new Transform({
transform(chunk, encoding, callback) {
const self = this;
setTimeout(() => {
self.push(processData(chunk));
callback();
}, 100);
}
});Use arrow functions in Transform definitions to avoid this binding issues.
Add proper error handling and test callbacks to catch hanging transforms:
const { Transform, pipeline } = require('stream');
const myTransform = new Transform({
timeout: 5000, // Optional: add timeout
transform(chunk, encoding, callback) {
try {
const result = processData(chunk);
callback(null, result);
} catch (err) {
callback(err);
}
}
});
// Add error listeners
myTransform.on('error', (err) => {
console.error('Transform error:', err);
});
// Use pipeline for proper error handling
const { pipeline } = require('stream/promises');
async function processStream() {
try {
await pipeline(
sourceStream,
myTransform,
destinationStream
);
console.log('Transform completed successfully');
} catch (err) {
console.error('Pipeline failed:', err);
// All streams are cleaned up automatically
}
}
// With timeout detection
const transformWithTimeout = new Transform({
transform(chunk, encoding, callback) {
const timeout = setTimeout(() => {
callback(new Error('Transform operation timed out'));
}, 5000);
try {
const result = processData(chunk);
clearTimeout(timeout);
callback(null, result);
} catch (err) {
clearTimeout(timeout);
callback(err);
}
}
});
processStream();Always add error event listeners and use pipeline() for automatic error propagation and cleanup.
Advanced notes
Backpressure Handling in Transform Streams
The callback is also your signal for backpressure management. When data accumulates in the transform buffer, handle it properly:
const { Transform } = require('stream');
const transformStream = new Transform({
highWaterMark: 16384, // Buffer threshold
transform(chunk, encoding, callback) {
// Process the chunk
const result = processData(chunk);
// Check if push() returns false (backpressure)
const canContinue = this.push(result);
if (!canContinue) {
// Buffer is full, pause incoming data
console.log('Backpressure detected');
}
// Always call callback to signal chunk is processed
callback();
}
});The callback signals to the writable side that the current chunk has been consumed and the transform is ready for the next chunk.
Distinguishing Between Filtering and No-Output Transforms
Transform streams can produce zero output for some inputs. Make sure to still call callback:
const { Transform } = require('stream');
// Filter transform: some chunks produce no output
const filterTransform = new Transform({
transform(chunk, encoding, callback) {
if (shouldKeep(chunk)) {
callback(null, chunk); // Output the chunk
} else {
callback(); // Skip this chunk, no output
}
}
});
// Aggregating transform: many inputs, one output
const aggregateTransform = new Transform({
transform(chunk, encoding, callback) {
this.buffer = this.buffer || [];
this.buffer.push(chunk);
if (this.buffer.length >= 10) {
const aggregated = combineChunks(this.buffer);
this.buffer = [];
callback(null, aggregated);
} else {
callback(); // No output yet
}
},
flush(callback) {
// Called when stream ends
if (this.buffer && this.buffer.length > 0) {
const aggregated = combineChunks(this.buffer);
callback(null, aggregated);
} else {
callback();
}
}
});The flush() method is called when the stream ends but buffered data remains. Always call callback here too.
Debugging Transform Stream Hangs
If your stream is hanging, add logging to track callback invocation:
const { Transform } = require('stream');
const debugTransform = new Transform({
transform(chunk, encoding, callback) {
console.log('Transform called with chunk:', chunk.toString());
try {
const result = processData(chunk);
console.log('Transform produced result:', result);
callback(null, result);
console.log('Callback invoked successfully');
} catch (err) {
console.error('Transform error:', err);
callback(err);
}
}
});
debugTransform.on('error', (err) => {
console.error('Stream error event:', err);
});
debugTransform.on('end', () => {
console.log('Stream ended');
});
debugTransform.on('finish', () => {
console.log('Stream finished writing');
});Use this debugging output to verify that _transform() is being called, is completing, and that callback is being invoked for each chunk.
Using Transform.from() for Simple Transforms
For simple, non-backpressure-heavy transforms, use Transform.from():
const { Transform } = require('stream');
// Simple async transform
const myTransform = Transform.from(async (chunk) => {
return await processData(chunk);
});
// Multiple outputs per input
const expandTransform = Transform.from(function* (chunk) {
for (const item of parseItems(chunk)) {
yield item;
}
});Transform.from() handles callback management automatically for you.
Frequently asked questions
- What does "Error: Transform stream callback not called (transform not pushed data" mean?
- A Transform stream callback error indicates that the _transform() method did not properly invoke its callback function or did not push any data to the stream output before completing. Transform streams are bidirectional: they accept input data, transform it, and output results through a callback mechanism. When the _transform() method is invoked with a chunk of data, you must either: 1.
- How do I fix "Error: Transform stream callback not called (transform not pushed data"?
- This error occurs when a Node.js Transform stream's _transform() method fails to call its callback function, or when the stream callback is invoked without data being pushed to the output buffer. It causes the stream to hang indefinitely, stopping all further data processing through the pipeline.
- What causes "Error: Transform stream callback not called (transform not pushed data"?
- Callback function is not called at all in _transform() method Async operation completes but callback is not invoked in the promise resolution Error in _transform() is thrown but not passed to callback(error)
- Is the "Error: Transform stream callback not called (transform not pushed data" error serious?
- Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.