psf/requests · error · TypeError

chunk_size must be an int, it is instead a

Error message

chunk_size must be an int, it is instead a {type(chunk_size)}.

What it means

Raised by Response.iter_content() when chunk_size is neither an int nor None. This is a runtime type guard added for untyped callers who pass the wrong type — the type signature already requires int | None. Without it, a bad value (e.g. a string) would propagate into urllib3's raw.read() or iter_slices() and produce a confusing downstream TypeError.

Solutions

Ensure chunk_size is an int literal or an explicitly converted int variable: int(my_var).
Pass None when you want all data in a single chunk (stream=False behavior).
If reading from config, wrap with int(): response.iter_content(chunk_size=int(config_value)).

Example fix

# before
resp.iter_content(chunk_size="8192")

# after
resp.iter_content(chunk_size=8192)

Defensive patterns

Strategy: type-guard

Validate before calling

if chunk_size is not None and not isinstance(chunk_size, int):
    raise TypeError(f'chunk_size must be int or None, got {type(chunk_size)}')
for chunk in resp.iter_content(chunk_size=chunk_size):
    ...

Type guard

def is_valid_chunk_size(v) -> bool:
    return v is None or (isinstance(v, int) and not isinstance(v, bool))

Prevention

Always pass int literals or explicitly converted int values to chunk_size.
Use a type checker (mypy/pyright) to catch type mismatches before runtime.
When reading chunk_size from config/env, always wrap with int().

When it happens

Trigger: Calling response.iter_content(chunk_size="1024"), response.iter_content(chunk_size=10.5) (float), response.iter_content(chunk_size=True) (bool is a subclass of int but edge cases exist), or passing any non-int/non-None value as chunk_size.

Common situations: Reading chunk_size from an environment variable or config file without converting from string; passing a float from a computed value (e.g. math.ceil result in some contexts); copy-pasting from documentation that shows a string literal.

Related errors

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

Appendix: source

Thrown at src/requests/models.py:963

                    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()
        elif chunk_size is not None and not isinstance(
            chunk_size, int
        ):  # runtime guard for untyped callers
            raise TypeError(
                f"chunk_size must be an int, it is instead a {type(chunk_size)}."
            )

        if self._content_consumed:
            # simulate reading small chunks of the content
            content = cast(bytes, self._content)
            chunks = iter_slices(content, chunk_size)
        else:
            chunks = generate()

        if decode_unicode:
            chunks = stream_decode_response_unicode(chunks, self)

        return chunks

    @overload
    def iter_lines(
        self,

View on GitHub (pinned to 8068356288)