streamGenerateContent returns null instead of Psr\Http\Message\ResponseInterface (Fatal TypeError in HttpTransporter::requestStream)

[cordelles3]

Describe the bug

Calling streamGenerateContent() causes a fatal TypeError inside the library’s internal HttpTransporter::requestStream() method.

Although the user-defined stream handler is invoked correctly and receives streamed chunks, the requestStream() method itself fails to return the required Psr\Http\Message\ResponseInterface object. Instead, it returns null, violating the function’s declared return type and terminating execution with a fatal error.

This occurs inside the closure used by HttpTransporter::sendRequest(), specifically in:

vendor/google-gemini-php/client/src/Transporters/HttpTransporter.php:68

(or near the end of the requestStream() method depending on the version).

---

To Reproduce

1. Install the library via Composer (version tested: 2.7.0).
2. Use the following code:

// The stream handler is correctly defined for side-effect output
$streamHandler = function (string $chunk): void {
    echo $chunk;
};

$client = \Gemini::factory()
    ->withApiKey($apiKey)
    ->withStreamHandler($streamHandler)
    ->make();

$result = $client
    ->generativeModel('gemini-2.0-flash')
    ->streamGenerateContent('Generate a short story.');

3. Run the script.

---

Expected behavior

• The streaming process should complete without fatal errors.
• requestStream() should return a valid Psr\Http\Message\ResponseInterface instance internally.
• Even if no final response body is produced, the function must not return null due to its strict return type.

---

Actual behavior

The PHP runtime terminates with:

PHP Fatal error: Uncaught TypeError: 
Gemini\Transporters\HttpTransporter::{closure:Gemini\Transporters\HttpTransporter::requestStream():68}(): 
Return value must be of type Psr\Http\Message\ResponseInterface, null returned 
in vendor/google-gemini-php/client/src/Transporters/HttpTransporter.php:68

Full stack trace confirms this originates entirely from internal library logic and not from the user-provided stream handler.

---

Workaround

Switch to the synchronous request method:

$result = $client
    ->generativeModel('gemini-2.0-flash')
    ->generateContent('Generate a short story.');

---

Environment

• PHP Version: 8.4.14
• Client Library Version: 2.7.0
• Operating System: Windows 11

---

Additional context

This behavior indicates a missing return statement or an unhandled branch in the streaming transport path.
The closure created inside requestStream() declares a Psr\Http\Message\ResponseInterface return type but returns null, which is guaranteed to fail under strict typing.

I can provide additional logs or a reproducible minimal case if needed.

[aydinfatih]

Hi @cordelles3

Thank you for the detailed report. However, there's a misunderstanding here.
The withStreamHandler() method is not for processing response chunks—it's for configuring how HTTP requests are sent with streaming enabled.
Looking at the documentation you linked, streaming works automatically without withStreamHandler():

$stream = $client->generativeModel('gemini-2.0-flash')
    ->streamGenerateContent('Tell me a story.');

foreach ($stream as $response) {
    echo $response->text();
}

You only need withStreamHandler() if you're using a custom PSR-18 HTTP client that doesn't support streaming—and even then, it must accept RequestInterface and return ResponseInterface, not process chunks.
The fatal error occurs because your Closure signature is incorrect. Simply remove the withStreamHandler() call entirely—the library handles streaming out of the box with Guzzle or PSR-18 clients.

[aydinfatih]

I'm closing this issue for now. If the problem persists, please don't hesitate to reopen it.