laravel response stream download returns empty file

laravel response stream download returns empty file

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Why Laravel Response Stream Downloads Return Empty Files When Streaming TSV Data

You are experiencing a classic buffering issue where data is successfully retrieved from an external API but vanishes before it reaches the client's browser. In your specific scenario, you are using Guzzle to fetch a TSV (Tab-Separated Values) file from a third-party endpoint and attempting to serve it as a stream download in a Laravel 5.4 controller. The fact that the raw getContents() call returns valid data proves the network request succeeded; however, the empty file output indicates a disconnect between how you are reading the response body and how you are writing it to the output stream.

The root cause lies in the implementation of the closure passed to response()->stream(). In your current code, you are defining the closure $file but leaving it empty:

return response()->stream(function () {
    // Empty closure - nothing is written to the stream here
}, 200, $headers);

When Guzzle executes $response->getBody()->getContents(), it reads the entire response body from the upstream API into memory and returns a string. By assigning this to $file, you have created a variable holding the data. However, simply storing that data in a variable inside the closure is insufficient for streaming. The Laravel stream helper expects the closure to explicitly write bytes to the stream resource it provides or return content directly via an internal mechanism that bypasses buffering.

To fix this, you must manually write the contents of the $file variable into the stream provided by the stream helper. Since you have already loaded the full contents into memory using getContents(), you are effectively doing a "fake" stream where all data resides in RAM before being written to the output buffer. You can achieve this by accessing the underlying stream resource within the closure and writing the string content directly to it.

Here is the corrected implementation for your Laravel 5.4 controller:

$fileContents = $response->getBody()->getContents();
$file_name = $filterArr['client_name'] . '_' . Carbon::now()->toDateString() . '.tsv';
$headers = [
    'Content-Disposition' => 'attachment; filename=' . $file_name,
    'Content-Type'        => 'text/tab-separated-values', // Explicitly set based on API response
];

return response()->stream(function ($output) use ($fileContents) {
    $output->write($fileContents);
}, 200, $headers);

In this approach, the $output parameter provided by the closure is a stream resource. Calling $output->write() ensures that the data stored in $fileContents is pushed into the HTTP response buffer before being sent to the browser. Without this explicit write operation, Laravel does not automatically flush the variable contents into the stream, resulting in the empty file you observed.

Additionally, pay close attention to the Content-Type header. Your API returned text/tab-separated-values, but your original code did not explicitly set this on the outgoing response. While browsers are often forgiving, explicitly setting the Content-Type header ensures that the user agent treats the file correctly as a downloadable text stream rather than trying to interpret it as HTML or JSON. If you were using Laravel 8 or higher, you could also consider using the Response::download() helper with a custom callback, but in Laravel 5.4, manual stream manipulation is the standard approach for this use case.

Be aware that loading the entire response into memory via getContents() works fine for small datasets like your TSV example. However, if the API returns gigabytes of data, this method will cause high memory usage and potential crashes. In such scenarios, you would need to iterate over the Guzzle stream directly using $response->getBody()->read() inside a loop or use chunked reading strategies instead of loading everything at once. For now, ensuring the write() call is present in your closure resolves the immediate issue of the empty file.

Our network