Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

A NestJS file stream returns an empty body or the wrong file type

ErrorThe CSV download opens as a binary file or has no name

Short answer

NestJS sends what the handler returns. Wrap a Readable stream or a Buffer in StreamableFile and return it. Its default Content-Type is application/octet-stream, so set type or a Content-Type header for CSV. If you inject @Res, enable passthrough: true so Nest still sends the returned file.

  • Applies to NestJS 10, NestJS 11, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Request the endpoint with curl and read the response headers: the Content-Type and Content-Disposition tell you what the server really sent.

    curl -i http://localhost:3000/reports/users.csv
  2. 2Match what you see, then jump to its fix

    1. 1Content-Type: application/octet-stream in the response, and the browser saves or shows binaryThe default content type is octet-streamFix
    2. 2The handler returns a StreamableFile but only starts misbehaving once @Res() is injected@Res() is injected without passthroughFix
    3. 3The download is empty or unreadable after passing a string or objectA plain string or object is wrapped in StreamableFileFix

What does the error look like?

  • The CSV download opens as a binary file or has no name
  • The response misbehaves after adding @Res() to a handler that returns a StreamableFile
  • A string or object passed to StreamableFile gives an unusable file

Cause 1 of 3

The default content type is octet-stream

1Check

The Nest docs say the Content-Type of a StreamableFile defaults to application/octet-stream.

curl -sI http://localhost:3000/reports/users.csv | grep -i content-type

2Fix

Pass type and disposition in the StreamableFile options, or set the header with the Header decorator.

import { Controller, Get, StreamableFile } from '@nestjs/common'
import { createReadStream } from 'node:fs'
import { join } from 'node:path'

@Controller('reports')
export class ReportsController {
  @Get('users.csv')
  getCsv(): StreamableFile {
    const file = createReadStream(join(process.cwd(), 'users.csv'))
    return new StreamableFile(file, {
      type: 'text/csv',
      disposition: 'attachment; filename="users.csv"',
    })
  }
}

3Verify

Run the same curl and check the header.

curl -sI http://localhost:3000/reports/users.csv | grep -i content-

Confirmed by docs.nestjs.com

Did this fix it?

Cause 2 of 3

@Res() is injected without passthrough

1Check

Injecting the response object normally hands the response to you. The Nest docs say to inject it with passthrough enabled when you only want to set headers and still return the file.

grep -rn "@Res(" src

2Fix

Use @Res({ passthrough: true }) and keep returning the StreamableFile.

@Get('users.csv')
getCsv(@Res({ passthrough: true }) res: Response): StreamableFile {
  res.set({ 'Content-Type': 'text/csv' })
  return new StreamableFile(createReadStream('users.csv'))
}

3Verify

Request the endpoint and check that the full file arrives.

curl -s http://localhost:3000/reports/users.csv | head

Confirmed by docs.nestjs.com

Did this fix it?

Cause 3 of 3

A plain string or object is wrapped in StreamableFile

1Check

The constructor accepts a Readable stream or a Uint8Array such as a Buffer.

grep -rn "new StreamableFile(" src

2Fix

Turn the text into a Buffer first, or stream it from a Readable.

const csv = 'id,name\n1,Ali\n'
return new StreamableFile(Buffer.from(csv), { type: 'text/csv' })

3Verify

Download the file and open it; the rows are visible.

curl -s http://localhost:3000/reports/users.csv

Confirmed by docs.nestjs.com

Did this fix it?

How do I stop it coming back?

  • Always set the type for non-binary downloads.
  • Use passthrough: true with @Res() unless you really want to write the response yourself.
  • Check headers with curl -i, not only in the browser.

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

NestJS GraphQL cannot work out the output type of a field or query

Cannot determine a GraphQL output type for the "<name>". Make sure your class is decorated with an appropriate decorator.

In code-first mode Nest reads TypeScript types through decorators, and arrays, promises and unions disappear at runtime.

2 causes, each with a fix

Back end

IntelliJ IDEA breakpoints are ignored in a NestJS app

No 'Debugger listening' line appears when the NestJS app starts

IntelliJ can only debug a NestJS app when the Node.js process runs with the inspector on and the IDE attaches to its port.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.