How to fix Error: Stream write timeout (write operation exceeded time limit) in Node.js

Node.jsINTERMEDIATEHIGH

This error occurs when a write operation to a Node.js stream takes longer than the configured timeout threshold. It typically happens when downstream consumers are slow or unresponsive, causing backpressure to accumulate and the write operation to stall.

What this error means

The "Stream write timeout" error indicates that a write operation to a writable stream has exceeded an enforced time limit. This typically occurs in scenarios where: 1. The receiving end (downstream consumer) is not consuming data fast enough, causing the internal write buffer to fill up 2. Network conditions are degraded, introducing latency into the transmission 3. The process handling the stream data is blocked or overloaded 4. A timeout has been explicitly set on the socket or stream, and the operation takes too long to complete This error is different from a simple failure—it means the operation started but couldn't complete within the allowed time window. It often occurs during large file transfers, streaming large amounts of data, or when piping between processes with mismatched throughput.

How to fix "Error: Stream write timeout (write operation exceeded time limit)"

1Handle write timeout errors in stream code

Add error handlers to catch and respond to timeout errors gracefully:

javascript

const fs = require('fs');
const stream = fs.createWriteStream('large-file.txt');

stream.on('error', (err) => {
  if (err.code === 'ETIMEDOUT') {
    console.error('Write operation timed out - receiver too slow');
    // Pause and retry with longer timeout, or fail gracefully
  } else {
    console.error('Stream error:', err);
  }
});

stream.write(data, (err) => {
  if (err) {
    if (err.code === 'ETIMEDOUT') {
      console.error('Write callback timeout');
    }
  }
});

For HTTP/socket operations:

javascript

const socket = req.socket;

socket.on('timeout', () => {
  console.error('Socket timeout during write');
  socket.destroy();
});

socket.setTimeout(60000); // 60 second timeout

2Respect backpressure to prevent write delays

The key to avoiding write timeouts is respecting backpressure—pause writing when the buffer is full and resume when it drains:

javascript

const fs = require('fs');

function writeWithBackpressure(readStream, writeStream) {
  let isPaused = false;

  readStream.on('data', (chunk) => {
    const canContinue = writeStream.write(chunk);

    if (!canContinue) {
      console.log('Buffer full, pausing read');
      readStream.pause();
      isPaused = true;
    }
  });

  writeStream.on('drain', () => {
    if (isPaused) {
      console.log('Buffer drained, resuming read');
      readStream.resume();
      isPaused = false;
    }
  });
}

const input = fs.createReadStream('input.txt');
const output = fs.createWriteStream('output.txt');

writeWithBackpressure(input, output);

Or use automatic piping which handles backpressure:

javascript

const input = fs.createReadStream('input.txt');
const output = fs.createWriteStream('output.txt');

input.pipe(output); // Automatically handles backpressure

3Increase timeout values appropriately

If the timeout is too strict for your use case, increase it based on the expected operation duration:

javascript

const net = require('net');

const socket = net.createConnection({
  host: 'server.example.com',
  port: 3000
});

// Set a longer timeout for large transfers (5 minutes)
socket.setTimeout(300000);

socket.on('timeout', () => {
  console.log('Write operation exceeded 5 minute timeout');
  socket.destroy();
});

socket.write(largeData);

For HTTP requests:

javascript

const http = require('http');

const req = http.request({
  hostname: 'example.com',
  path: '/upload',
  method: 'POST',
  timeout: 300000 // 5 minutes
}, (res) => {
  console.log('Response received');
});

req.on('timeout', () => {
  console.error('Request timeout');
  req.abort();
});

req.write(largeData);

4Use stream.pipeline() for automatic timeout handling

The stream.pipeline() API provides better error handling and can help prevent timeout scenarios:

javascript

const { pipeline } = require('stream');
const fs = require('fs');
const zlib = require('zlib');

pipeline(
  fs.createReadStream('input.txt'),
  zlib.createGzip(),
  fs.createWriteStream('input.txt.gz'),
  (err) => {
    if (err) {
      if (err.code === 'ETIMEDOUT') {
        console.error('Pipeline write operation timed out');
      } else {
        console.error('Pipeline failed:', err);
      }
      // Clean up is automatic
    } else {
      console.log('Pipeline succeeded');
    }
  }
);

Pipeline automatically:
- Respects backpressure
- Propagates errors from any stage
- Cleans up all streams on error

5Increase buffer size (highWaterMark) for better throughput

If data is backing up, increase the stream buffer size to allow more data before backpressure kicks in:

javascript

const fs = require('fs');

// Default highWaterMark is 16KB for most streams
const readStream = fs.createReadStream('large-file.bin', {
  highWaterMark: 256 * 1024 // 256 KB buffer
});

const writeStream = fs.createWriteStream('output.bin', {
  highWaterMark: 256 * 1024 // Larger buffer = less frequent backpressure
});

// Respect backpressure even with larger buffer
let isPaused = false;

readStream.on('data', (chunk) => {
  const ok = writeStream.write(chunk);
  if (!ok) {
    readStream.pause();
    isPaused = true;
  }
});

writeStream.on('drain', () => {
  if (isPaused) {
    readStream.resume();
    isPaused = false;
  }
});

Note: Larger buffers use more memory but can reduce backpressure-induced stalls.

6Monitor and debug stream performance

Add visibility into stream throughput and timeout conditions:

javascript

const { pipeline } = require('stream');
const fs = require('fs');

function createMonitoringStream() {
  let bytesWritten = 0;
  const startTime = Date.now();

  return {
    logStats: () => {
      const elapsedMs = Date.now() - startTime;
      const throughputMBps = (bytesWritten / (1024 * 1024)) / (elapsedMs / 1000);
      console.log(`Throughput: ${throughputMBps.toFixed(2)} MB/s, Total: ${(bytesWritten / 1024 / 1024).toFixed(2)} MB`);
    },
    track: (bytes) => {
      bytesWritten += bytes;
    }
  };
}

const monitor = createMonitoringStream();

pipeline(
  fs.createReadStream('large-file.bin'),
  {
    // Custom transform to track bytes
    transform(chunk, encoding, callback) {
      monitor.track(chunk.length);
      if (Date.now() % 1000 === 0) {
        monitor.logStats();
      }
      callback(null, chunk);
    }
  },
  fs.createWriteStream('output.bin'),
  (err) => {
    if (err) {
      console.error('Pipeline error:', err);
    } else {
      monitor.logStats();
    }
  }
);

Advanced notes

Backpressure and Memory Management: Stream timeouts often mask underlying backpressure issues. If writes are timing out, it usually means the receiving end can't keep up. Ignoring backpressure and retrying writes will cause memory to accumulate in Node.js process buffers, eventually leading to out-of-memory errors. Always respect the return value of stream.write() and listen for the 'drain' event.

highWaterMark Tuning: The default highWaterMark (typically 16KB for object streams, 64KB for binary streams) might be too small for high-throughput scenarios. However, increasing it too much wastes memory. Monitor your application's throughput and adjust based on actual performance data. For large file transfers, 256KB to 1MB is often appropriate.

TCP Window Size and Network Considerations: Even with proper backpressure handling in Node.js, network-level issues can cause timeouts. TCP window scaling and network middleware (proxies, load balancers) can affect throughput. If timeouts persist despite correct code, investigate network-level bottlenecks.

Socket vs Stream Timeouts: Node.js sockets have their own timeout mechanism separate from stream write timeouts. A socket timeout will trigger a 'timeout' event and often an ETIMEDOUT error. Always set appropriate socket timeouts for network I/O, as they serve as a safety net when backpressure handling fails.

Chunked Encoding and HTTP: When streaming HTTP responses, Node.js uses chunked transfer encoding by default. Very large chunks can exceed TCP window sizes and cause delays. Consider limiting individual chunk sizes to 64KB-256KB for HTTP streaming to balance throughput with responsiveness.

Production Monitoring: In production, log all timeout errors with context (bytes written, duration, throughput estimate). This data helps identify whether timeouts are caused by slow clients, network issues, or application performance problems. Tools like New Relic or Datadog can track stream performance across your infrastructure.

Graceful Degradation: Instead of failing immediately on timeout, consider implementing retry logic with exponential backoff or fallback mechanisms (e.g., switch to chunked delivery, compress data, reduce payload size).

How to fix Error: Stream write timeout (write operation exceeded time limit) in Node.js

What this error means

Typical symptoms

Common causes

How to fix "Error: Stream write timeout (write operation exceeded time limit)"

Advanced notes

Related errors

Official resources & further reading