A NestJS file stream returns an empty body or the wrong file type
The CSV download opens as a binary file or has no nameShort 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.
Fix it fast
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.csv2Match what you see, then jump to its fix
- 1
Content-Type: application/octet-stream in the response, and the browser saves or shows binaryThe default content type is octet-streamFix - 2
The handler returns a StreamableFile but only starts misbehaving once @Res() is injected@Res() is injected without passthroughFix - 3
The download is empty or unreadable after passing a string or objectA plain string or object is wrapped in StreamableFileFix
- 1
What does the error look like?
The CSV download opens as a binary file or has no nameThe response misbehaves after adding @Res() to a handler that returns a StreamableFileA 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-type2Fix
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
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(" src2Fix
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 | headConfirmed by docs.nestjs.com
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(" src2Fix
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.csvConfirmed by docs.nestjs.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
TypeScript cannot find module '@nestjs/core' or its type declarations
error TS2307: Cannot find module '@nestjs/common' or its corresponding type declarations.
TS2307 means TypeScript searched node_modules and found neither the package nor its types.
3 causes, each with a fixBack end
Node.js in Docker Compose cannot reach MySQL on 127.0.0.1:3306
Error: connect ECONNREFUSED 127.0.0.1:3306
Inside a container, 127.0.0.1 is that container, not MySQL.
3 causes, each with a fixBack 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 fixBack 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 fixBack end
The nest command is not found in the terminal
bash: nest: command not found
The shell cannot find a nest executable on its PATH.
3 causes, each with a fixBack end
NestJS watch mode does not restart after I save a file
Changes show on the host but not in the running container
Watch mode only sees files that exist inside the process that runs it.
3 causes, each with a fix