{"record":{"id":"71c467f405249553","repo":"guzzle/guzzle","slug":"failed-while-transferring-the-response-body","errorCode":null,"errorMessage":"Failed while transferring the response body","messagePattern":"Failed while transferring the response body","errorType":"exception","errorClass":"GuzzleHttp\\Exception\\ResponseTransferException","httpStatus":null,"severity":"error","filePath":"src/Handler/StreamHandler.php","lineNumber":710,"sourceCode":"                // that number of bytes has been read. This can prevent infinitely\n                // reading from a stream when dealing with servers that do not\n                // honor Connection: Close headers.\n                $copied = Psr7\\Utils::copyToStream($source, $target, $copyLimit);\n            } catch (ResponseException $e) {\n                throw $e;\n            } catch (TimeoutException $e) {\n                throw new ResponseTimeoutException(\n                    'Timed out while transferring the response body',\n                    $request,\n                    $response,\n                    $e\n                );\n            } catch (\\OverflowException $e) {\n                throw new ResponseException($e->getMessage(), $request, $response, $e);\n            } catch (\\Exception $e) {\n                // Any other response-body transfer failure surfaces as a\n                // ResponseTransferException carrying the response.\n                throw new ResponseTransferException(\n                    $e->getMessage() !== '' ? $e->getMessage() : 'Failed while transferring the response body',\n                    $request,\n                    $response,\n                    $e\n                );\n            }\n\n            $receivedLength = $encodedBody !== null ? $encodedBody->getBytesRead() : $copied;\n            if ($declaredLength !== null && $receivedLength < $declaredLength) {\n                throw new ResponseTransferException(\n                    'Response body ended before the declared Content-Length was reached',\n                    $request,\n                    $response\n                );\n            }\n\n            try {\n                if ($sink->isSeekable()) {","sourceCodeStart":692,"sourceCodeEnd":728,"githubUrl":"https://github.com/guzzle/guzzle/blob/d1cbca76970939a9c2ced55b1e25ea26f34fc773/src/Handler/StreamHandler.php#L692-L728","documentation":"Thrown by StreamHandler::drain() when copying the response body fails with any Exception that is not a ResponseException, TimeoutException, or OverflowException (those are handled earlier). It is wrapped as a ResponseTransferException using the original $e->getMessage() when non-empty, else the fallback 'Failed while transferring the response body'. It carries the request, response, and the underlying exception.","triggerScenarios":"An I/O failure mid-body that is not a timeout: the transport stream read() throws a RuntimeException (e.g. SSL connection reset not matched to the network-error list, broken pipe, filter error), or a dechunk/inflate filter raises. The generic catch is at src/Handler/StreamHandler.php:707.","commonSituations":"Connection reset by peer while reading the body; SSL errors during body transfer; zlib inflate failure on a corrupt gzip body; broken pipe from an intermediary proxy; intermittent network errors.","solutions":["Inspect the previous exception ($e->getPrevious()) for the real transport error and address that (TLS, connectivity, corrupt encoding).","Retry idempotent requests; the response is partial and unusable.","For large bodies, stream to disk and enable retry with Range/offset to resume."],"exampleFix":"// before\ntry { $client->get($u); }\ncatch (\\GuzzleHttp\\Exception\\ResponseTransferException $e) { /* generic, lose detail */ }\n// after\ntry { $client->get($u); }\ncatch (\\GuzzleHttp\\Exception\\ResponseTransferException $e) {\n    $cause = $e->getPrevious() ? $e->getPrevious()->getMessage() : $e->getMessage();\n    $logger->error('body transfer failed: '.$cause); // act on the real cause\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    $resp = $client->get($u);\n} catch (\\GuzzleHttp\\Exception\\ResponseTransferException $e) {\n    $cause = $e->getPrevious();\n    // only retry idempotent methods; log the underlying cause for diagnosis\n    if (in_array($method, ['GET','HEAD','PUT','DELETE'], true)) {\n        $resp = $client->get($u);\n    }\n}","preventionTips":["Inspect getPrevious() to find the real transport error before retrying.","Retry only idempotent requests on mid-body transfer failures.","Stream large bodies to a sink so partial progress can be resumed with Range."],"tags":["response-body","transfer","stream-handler","io-error"],"backgroundTag":null,"analyzedSha":"d1cbca76970939a9c2ced55b1e25ea26f34fc773","analyzedAt":"2026-08-06T00:37:27.795Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}