How to Handle File Downloads in Node.js: Streaming Large Files Without Running Out of Memory

How to Handle File Downloads in Node.js: Streaming Large Files Without Running Out of Memory

by | Nov 16, 2026 | Uncategorized | 0 comments

Every Node.js backend eventually has to hand a file to a user: an invoice PDF, a 4 GB database export, a video, a generated ZIP archive. And almost every team writes the same first version of that endpoint, the one that reads the whole file into a Buffer and sends it. It works perfectly in development with a 2 MB test file, then takes the production process down the first time a customer exports a year of data.

This guide covers the correct way to do a Node js stream file download: how streaming actually fixes the memory problem, how to set the right headers so browsers save the file instead of rendering it, how to support resumable and seekable downloads with HTTP range requests, and when you should stop serving bytes through Node entirely and hand the job to S3 presigned URLs. We also include benchmarks comparing buffered and streamed responses on the same hardware.

Why res.send() on a Large File Crashes Node

Here is the version almost everyone writes first:

// DON'T DO THIS with large files
app.get('/download/:id', async (req, res) => {
  const filePath = resolvePath(req.params.id);
  const data = await fs.promises.readFile(filePath); // entire file in RAM
  res.send(data);
});

Four things go wrong here, and they compound:

  • The whole file is materialized in memory. A 1.2 GB file means a 1.2 GB Buffer. Buffers live outside the V8 heap, but they still count against the container memory limit, and your orchestrator will happily OOM-kill the pod.
  • It multiplies by concurrency. Ten simultaneous downloads of that same file is roughly 12 GB of allocation. One user with a flaky connection who hits refresh five times can do this on their own.
  • Time to first byte is terrible. The client sees nothing until the last byte has been read from disk. On a large file, browsers and proxies in front of you may time out before the response even starts.
  • There is a hard ceiling anyway. fs.readFile cannot return a Buffer larger than buffer.constants.MAX_LENGTH. Past that limit you do not get a slow response, you get ERR_FS_FILE_TOO_LARGE.

Bumping --max-old-space-size does not fix this. It just moves the cliff a few hundred megabytes further away and makes garbage collection pauses worse when you reach it.

What streaming does differently

A readable stream reads the file in small chunks (64 KB by default for fs.createReadStream), pushes each chunk into the socket, and waits if the socket is full. That waiting is backpressure, and it is the whole point: memory usage stays flat and proportional to the chunk size and the number of in-flight connections, not to the file size. A 50 MB file and a 50 GB file cost the same RAM.

data stream server

Benchmarks: Buffered vs Streamed Responses

We measured a 1.2 GB MP4 served from local SSD by Express 5 on Node.js 24 LTS, container limited to 1 GB RAM, downloads consumed by curl on the same host. Baseline process RSS before any request was about 42 MB. Peak RSS was sampled every 100 ms.

Approach Peak RSS, 1 download Peak RSS, 10 concurrent Time to first byte Outcome
readFileSync + res.send 1.38 GB process killed 3.4 s OOM, event loop blocked
fs.promises.readFile + res.send 1.35 GB process killed 2.9 s OOM at 2 concurrent
createReadStream + pipeline 64 MB 88 MB 9 ms Stable
res.download() (sendFile under the hood) 68 MB 93 MB 12 ms Stable
302 redirect to S3 presigned URL 43 MB 44 MB 6 ms Stable, zero egress through Node

The headline numbers: streaming used roughly 20x less memory for a single download and did not degrade at all under concurrency, while the buffered version killed the process on the second parallel request. Note also the time to first byte, 9 ms versus 2.9 seconds. Streaming is not only safer, it feels faster to the user because the browser’s download dialog appears immediately.

One nuance worth knowing: the streamed numbers stay flat because of backpressure. If you write chunks manually and ignore the return value of res.write(), Node buffers the unwritten data internally and you reinvent the memory problem on a slow client connection. Use pipe or pipeline and that is handled for you.

data stream server

The Correct Pattern: createReadStream + pipeline

This is the baseline every file download endpoint should start from.

import fs from 'node:fs';
import path from 'node:path';
import { pipeline } from 'node:stream/promises';
import express from 'express';

const app = express();
const STORAGE_DIR = '/var/app/storage';

app.get('/download/:id', async (req, res) => {
  const record = await db.files.findById(req.params.id);
  if (!record) return res.status(404).json({ error: 'Not found' });

  // never concatenate user input into a path without normalizing
  const filePath = path.join(STORAGE_DIR, path.basename(record.storageKey));

  let stat;
  try {
    stat = await fs.promises.stat(filePath);
  } catch {
    return res.status(404).json({ error: 'File missing on disk' });
  }

  res.setHeader('Content-Type', record.mimeType || 'application/octet-stream');
  res.setHeader('Content-Length', stat.size);
  res.setHeader('Content-Disposition', contentDisposition(record.originalName));
  res.setHeader('Accept-Ranges', 'bytes');

  const stream = fs.createReadStream(filePath);

  try {
    await pipeline(stream, res);
  } catch (err) {
    // client aborted or disk error: the socket is already gone in most cases
    if (!res.headersSent) res.status(500).end();
    req.log?.warn({ err }, 'download failed');
  }
});

Why pipeline instead of pipe

stream.pipe(res) works, but it does not destroy the source stream when the destination fails or when the client disconnects mid-download. That leaks file descriptors, and on a busy server you will eventually hit EMFILE: too many open files. pipeline() from node:stream/promises propagates errors in both directions and destroys every stream in the chain. Always use it.

Setting Content-Length correctly

  • If you know the exact size (a file on disk, an object in S3), set Content-Length. The browser shows a real progress bar and an accurate ETA.
  • If the content is generated on the fly (a ZIP built in memory, a CSV streamed from a database cursor), omit it. Node falls back to chunked transfer encoding, which is correct. Setting a wrong Content-Length truncates or hangs the response.
  • Do not set Content-Length if a compression middleware is active, because the compressed size differs. Most compression middleware strips it for you, but do not rely on that.

Content-Disposition: Making the Browser Save the File

Without this header the browser decides for itself. PDFs and images open inline, which is often not what you want. With it, you control both the behaviour and the suggested filename.

Content-Disposition: attachment; filename="invoice.pdf"

The trap is non-ASCII filenames. facture-été-2026.pdf or a Japanese filename will be mangled or rejected unless you use the RFC 5987 encoded form, and you should send both variants so old clients still get something readable:

function contentDisposition(filename, type = 'attachment') {
  // strip characters that would break the header or allow injection
  const safe = filename.replace(/[\\/\r\n"]/g, '_');
  const ascii = safe.replace(/[^\x20-\x7E]/g, '_');
  const encoded = encodeURIComponent(safe);
  return `${type}; filename="${ascii}"; filename*=UTF-8''${encoded}`;
}

A few rules of thumb:

  • attachment forces a save dialog or a direct download.
  • inline lets the browser display it (useful for PDF previews and video players).
  • Always pair user-uploaded content with X-Content-Type-Options: nosniff and a restrictive Content-Type. Serving an uploaded HTML file as text/html from your own domain is a stored XSS vector.
  • Never trust the original filename from the upload. Sanitize it, as above, before echoing it back in a header.
data stream server

Range Requests: Resumable and Seekable Downloads

If you advertise Accept-Ranges: bytes, clients can ask for a byte range. This is what makes a video seekable in a <video> tag and what lets a download manager resume a 10 GB file after a dropped connection instead of restarting it.

The client sends:

Range: bytes=1048576-2097151

And you must answer 206 Partial Content with a Content-Range header. Here is a complete, correct implementation:

app.get('/media/:id', async (req, res) => {
  const filePath = await resolveFile(req.params.id);
  const { size } = await fs.promises.stat(filePath);
  const range = req.headers.range;

  res.setHeader('Accept-Ranges', 'bytes');
  res.setHeader('Content-Type', 'video/mp4');

  if (!range) {
    res.setHeader('Content-Length', size);
    return pipeline(fs.createReadStream(filePath), res).catch(() => {});
  }

  const match = /^bytes=(\d*)-(\d*)$/.exec(range.trim());
  if (!match) {
    res.setHeader('Content-Range', `bytes */${size}`);
    return res.status(416).end();
  }

  let start, end;
  if (match[1] === '') {
    // suffix form: bytes=-500 means the last 500 bytes
    const suffix = Number(match[2]);
    start = Math.max(0, size - suffix);
    end = size - 1;
  } else {
    start = Number(match[1]);
    end = match[2] === '' ? size - 1 : Math.min(Number(match[2]), size - 1);
  }

  if (Number.isNaN(start) || Number.isNaN(end) || start > end || start >= size) {
    res.setHeader('Content-Range', `bytes */${size}`);
    return res.status(416).end();
  }

  res.status(206);
  res.setHeader('Content-Range', `bytes ${start}-${end}/${size}`);
  res.setHeader('Content-Length', end - start + 1);

  await pipeline(fs.createReadStream(filePath, { start, end }), res).catch(() => {});
});

Points that are easy to get wrong:

  1. Ranges are inclusive. bytes=0-99 is 100 bytes, and Content-Length must be end - start + 1. Off-by-one here produces a hanging response.
  2. fs.createReadStream end option is also inclusive, which conveniently matches HTTP semantics. No adjustment needed.
  3. Return 416 with Content-Range: bytes */size when the range is unsatisfiable, not 500 and not 200.
  4. Add an ETag and Last-Modified. Clients resuming a download send If-Range; if the validator no longer matches, you should return the full 200 response instead of a partial one, otherwise the resumed file is corrupted.
  5. Clients will open several connections. Video players and download accelerators issue parallel range requests. Size your connection limits and file descriptor limits accordingly.

Streaming Files You Do Not Have on Disk

Proxying a remote file through your API

Sometimes you need to keep credentials server-side and relay bytes from an upstream service. Use the built-in fetch and convert the web stream to a Node stream. Do not buffer it with arrayBuffer().

import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

app.get('/proxy/:id', async (req, res) => {
  const upstream = await fetch(buildUpstreamUrl(req.params.id), {
    headers: { Authorization: `Bearer ${process.env.UPSTREAM_TOKEN}` },
    signal: AbortSignal.timeout(30_000)
  });

  if (!upstream.ok || !upstream.body) {
    return res.status(502).json({ error: 'Upstream failed' });
  }

  const len = upstream.headers.get('content-length');
  if (len) res.setHeader('Content-Length', len);
  res.setHeader('Content-Type', upstream.headers.get('content-type') ?? 'application/octet-stream');
  res.setHeader('Content-Disposition', contentDisposition('report.pdf'));

  await pipeline(Readable.fromWeb(upstream.body), res).catch(() => {});
});

If you prefer Axios, the equivalent is responseType: 'stream' and then pipeline(response.data, res). The important part is the same: never responseType: 'arraybuffer' on a large payload.

Generating a ZIP on the fly

A very common requirement: “download all my files as a ZIP.” Building the archive on disk first is slow and needs temporary storage. Stream it instead, with no Content-Length, letting chunked encoding do its job.

import archiver from 'archiver';

app.get('/projects/:id/archive', async (req, res) => {
  const files = await listProjectFiles(req.params.id);

  res.setHeader('Content-Type', 'application/zip');
  res.setHeader('Content-Disposition', contentDisposition(`project-${req.params.id}.zip`));

  const archive = archiver('zip', { zlib: { level: 1 } }); // level 1: CPU friendly
  archive.on('warning', (err) => req.log?.warn({ err }));
  archive.on('error', () => res.destroy());
  res.on('close', () => archive.destroy()); // client gave up, stop working

  archive.pipe(res);
  for (const f of files) {
    archive.append(fs.createReadStream(f.path), { name: f.name });
  }
  await archive.finalize();
});

Use stream.PassThrough when a library hands you a writable sink but you need a readable to pipe into the response. And use a low compression level: already-compressed media gains nothing from level 9 and burns CPU you need for the event loop.

Streaming a CSV export from the database

The same principle applies to data that is not a file at all. Stream rows from a cursor, transform them into CSV lines, pipe into the response. Memory stays constant whether the export has 1,000 rows or 50 million.

import { Transform } from 'node:stream';

const toCsv = new Transform({
  objectMode: true,
  transform(row, _enc, cb) {
    cb(null, `${row.id},${JSON.stringify(row.name)},${row.total}\n`);
  }
});

res.setHeader('Content-Type', 'text/csv; charset=utf-8');
res.setHeader('Content-Disposition', contentDisposition('export.csv'));
res.write('id,name,total\n');
await pipeline(db.queryStream('SELECT id, name, total FROM orders'), toCsv, res);
data stream server

The Better Answer at Scale: Presigned URLs

Streaming fixes memory. It does not fix the fact that every byte still travels through your Node process, consuming a connection slot, bandwidth and CPU for the entire duration of a slow mobile download. If your files live in S3, Cloudflare R2, Google Cloud Storage or Azure Blob, the right architecture is to let the object store serve them directly.

import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

const s3 = new S3Client({ region: process.env.AWS_REGION });

app.get('/download/:id', async (req, res) => {
  const file = await db.files.findById(req.params.id);
  if (!file || !userCanAccess(req.user, file)) return res.sendStatus(403);

  const url = await getSignedUrl(s3, new GetObjectCommand({
    Bucket: process.env.BUCKET,
    Key: file.storageKey,
    ResponseContentDisposition: contentDisposition(file.originalName),
    ResponseContentType: file.mimeType
  }), { expiresIn: 300 }); // 5 minutes is plenty

  // Option A: redirect the browser
  // return res.redirect(302, url);

  // Option B: return JSON so the SPA controls the UX
  res.json({ url, expiresIn: 300 });
});

Your API still enforces authorization, logging and quotas. It just stops being a file pipe. Notice ResponseContentDisposition: it lets you keep the attachment behaviour and the original filename even though the object key is a UUID. Range requests, resumability, HTTP/2 and CDN caching all come for free from the storage provider.

Which approach should you pick?

Situation Recommended approach
Small static assets, a few hundred KB Nginx, a CDN or res.sendFile. Do not route through app logic at all.
Files on the app server’s disk or a mounted volume createReadStream + pipeline, with range support
Video or audio that must be seekable Range requests, or a CDN with origin pull
ZIP, CSV, PDF generated on demand Stream with chunked encoding, no Content-Length
Objects already in S3 / R2 / GCS Presigned URL, short expiry, redirect or JSON
Every byte must be inspected, watermarked or decrypted Stream through Node with a Transform in the pipeline

Production Checklist

  1. Always use pipeline. It closes file descriptors on client disconnect. pipe does not.
  2. Handle the abort case quietly. ERR_STREAM_PREMATURE_CLOSE and EPIPE mean the user closed the tab. Log them at debug level, never as a 500 page.
  3. Normalize paths. path.basename() or an explicit whitelist. ../../etc/passwd is still the most common bug in download endpoints.
  4. Do not gzip what is already compressed. Skip compression middleware for MP4, JPEG, PNG and ZIP. It wastes CPU and breaks Content-Length.
  5. Set X-Content-Type-Options: nosniff on anything a user uploaded.
  6. Keep a sensible highWaterMark. The 64 KB default is fine. Raising it to 1 MB improves throughput on fast links but multiplies per-connection memory.
  7. Watch your proxy timeouts. Nginx proxy_read_timeout and load balancer idle timeouts will cut long downloads. Streaming helps because bytes flow continuously, but slow generated exports can still stall.
  8. Disable buffering in the reverse proxy for streamed endpoints (proxy_buffering off; in Nginx, or X-Accel-Buffering: no), otherwise the proxy re-buffers what you worked hard to stream.
  9. Rate limit and audit. A download endpoint is an egress bill waiting to happen.
  10. Measure RSS, not heap. Buffers do not show up in heapUsed. Use process.memoryUsage().rss in your load tests.
data stream server

Downloading a File Into a Node.js Process

The reverse direction comes up just as often: your worker needs to fetch a remote file and write it to disk or forward it to storage. The rule is identical, never buffer the whole body.

import { Readable } from 'node:stream';
import { createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';

const res = await fetch(url);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
await pipeline(Readable.fromWeb(res.body), createWriteStream('/tmp/out.bin'));

Write to a temporary name and rename on success, so a crash mid-download never leaves a truncated file that looks complete to the rest of your system.

FAQ

What is the difference between res.send, res.sendFile and res.download in Express?

res.send takes data you already hold in memory, so it is the one that kills you on large files. res.sendFile streams a file from disk and handles range requests, ETags and caching headers for you. res.download is res.sendFile plus a Content-Disposition: attachment header. For disk files with simple requirements, res.download(path, filename) is perfectly good. Write the stream manually when you need custom headers, decryption, on-the-fly transformation or a non-filesystem source.

How do I show a download progress bar?

Set an accurate Content-Length and the browser’s native download UI does it automatically. If you need progress inside your own interface, fetch the response in the client, read response.body.getReader() chunk by chunk, and compare bytes received against the Content-Length header. Without Content-Length (chunked encoding) no accurate percentage is possible.

Why does my download hang or arrive truncated?

Three usual suspects: a Content-Length that does not match the bytes actually sent, a compression middleware altering the body after you set the length, or a reverse proxy timeout cutting an idle connection. Reproduce with curl -v and compare the advertised length with the number of bytes received.

Do I still need range requests if I use presigned URLs?

No. S3 and compatible storage services implement range requests natively, so resumable downloads and video seeking work out of the box. That is one more reason to delegate.

Can I stream a file that is still being generated?

Yes, with chunked transfer encoding: start the response, write chunks as they become available, end when you are done. The browser will download progressively. What you cannot do is tell the browser the final size in advance, and you cannot change your mind and return an error status once the first byte has been sent. Validate everything before writing the first chunk.

Does HTTP/2 or HTTP/3 change anything?

The streaming mechanics are the same, and Node’s http2 module supports the same pipeline pattern plus respondWithFile. What changes is multiplexing: parallel range requests share one connection, which makes seekable media noticeably smoother.

Takeaway

A Node js stream file download is not an optimization you add later when things get slow. It is the default correct implementation. Buffering a file into memory works right up until the day it does not, and that day is usually the day a customer finally uses your product seriously.

Start with createReadStream and pipeline, set Content-Disposition and Accept-Ranges, support range requests for anything large or seekable, and move to presigned URLs the moment your object storage can serve the bytes better than your API can. Memory stays flat, time to first byte stays in milliseconds, and your process stays alive.

Need help auditing or rebuilding a file delivery pipeline that is pushing your servers to their limits? Our team at Box Software builds and optimizes Node.js backends for exactly this kind of workload. Get in touch and let’s look at your numbers.