psf/requests · error · ChunkedEncodingError

{e}

Error message

{e}

What it means

Raised inside Response.iter_content's generator when self.raw.stream() raises a urllib3.exceptions.ProtocolError — typically a malformed chunk framing, a premature connection close mid-chunk, or a violated HTTP/1.1 transfer rule. requests wraps it as ChunkedEncodingError so callers can distinguish framing failures from generic connection errors. The message is the wrapped exception's string form.

Source

Thrown at src/requests/models.py:941

        chunk_size must be of type int or None. A value of None will
        function differently depending on the value of `stream`.
        stream=True will read data as it arrives in whatever size the
        chunks are received. If stream=False, data is returned as
        a single chunk.

        If decode_unicode is True, content will be decoded using encoding
        information from the response. If no encoding information is available,
        bytes will be returned. This can be bypassed by manually setting
        `encoding` on the response.
        """

        def generate() -> Generator[bytes, None, None]:
            # Special case for urllib3.
            if hasattr(self.raw, "stream"):
                try:
                    yield from self.raw.stream(chunk_size, decode_content=True)
                except ProtocolError as e:
                    raise ChunkedEncodingError(e)
                except DecodeError as e:
                    raise ContentDecodingError(e)
                except ReadTimeoutError as e:
                    raise ConnectionError(e)
                except SSLError as e:
                    raise RequestsSSLError(e)
            else:
                # Standard file-like object.
                while True:
                    chunk = self.raw.read(chunk_size)
                    if not chunk:
                        break
                    yield chunk

            self._content_consumed = True

        if self._content_consumed and isinstance(self._content, bool):
            raise StreamConsumedError()

View on GitHub (pinned to 8068356288)

Solutions

1. Wrap iter_content() consumption in try/except ChunkedEncodingError and either retry the request (with Range/resume if supported) or surface a clear 'incomplete response' error.
2. If you control the server, ensure chunked responses always emit the terminating zero-length chunk.
3. Disable intermediate proxies' chunked-buffering or upgrade them; retry with a shorter timeout to fail faster.

Example fix

// before
for chunk in resp.iter_content(8192):
    process(chunk)

// after
from requests.exceptions import ChunkedEncodingError
try:
    for chunk in resp.iter_content(8192):
        process(chunk)
except ChunkedEncodingError:
    # retry or mark partial
    ...

# Chunked framing errors cannot be reliably pre-validated client-side.
# Configure timeouts and resume support to mitigate:
session.mount('https://', HTTPAdapter(max_retries=Retry(total=3)))

# No client-side type guard; this is a transport-layer failure.
# Use a Response integrity check after consumption:
def is_complete(resp) -> bool:
    return resp.raw.closed and getattr(resp, '_elapsed', None) is not None

from requests.exceptions import ChunkedEncodingError

try:
    for chunk in resp.iter_content(8192):
        process(chunk)
except ChunkedEncodingError as e:
    # retry, resume (Range), or surface 'incomplete response'
    log.warning('chunked transfer failed: %s', e)
    raise

When it happens

Trigger: Server sends Transfer-Encoding: chunked but closes the socket before the terminating zero-length chunk; a proxy corrupts or truncates chunk boundaries; client reads with stream=True and the upstream interrupts mid-stream.

Common situations: Long-lived streaming endpoints (SSE, large downloads) behind flaky proxies; reverse proxies that mis-buffer chunked responses; mobile/flaky networks that drop connections mid-transfer.

Related errors

• Streamed bodies and files are mutually exclusive.
• {err}
• Auth hooks must be callable.
• Cookie headers should be added with add_unredirected_header(
• name={name!r}, domain={domain!r}, path={path!r}

AI-assisted analysis of psf/requests@8068356288 (2026-08-11). Data as JSON: /api/errors/73e43ac9f6be8a03. Report an issue: GitHub.