psf/requests · error · UnrewindableBodyError

Unable to rewind request body for redirect.

Error message

Unable to rewind request body for redirect.

What it means

Raised as `requests.exceptions.UnrewindableBodyError` from `rewind_body()` in `src/requests/utils.py:1155`. This is the branch where the request body either has no `seek()` method at all or requests never recorded a valid integer `_body_position` (it records `IncompleteRead`/failure sentinels when the initial `tell()` failed). Without both, the already-consumed streamed body cannot be replayed on a redirect, so requests refuses to follow it with a corrupt/empty body.

Source

Thrown at src/requests/utils.py:1155

def rewind_body(prepared_request: PreparedRequest) -> None:
    """Move file pointer back to its recorded starting position
    so it can be read again on redirect.
    """
    body_seek = getattr(prepared_request.body, "seek", None)
    if body_seek is not None and isinstance(
        prepared_request._body_position,
        integer_types,
    ):
        try:
            body_seek(prepared_request._body_position)
        except OSError:
            raise UnrewindableBodyError(
                "An error occurred when rewinding request body for redirect."
            )
    else:
        raise UnrewindableBodyError("Unable to rewind request body for redirect.")

View on GitHub ↗ (pinned to 414f0513c3)

Solutions

1. Point the request at the final, canonical URL (https, correct host, trailing slash) so no redirect happens — this is the usual fix.
2. Replace the generator/iterator body with a seekable object: read it into `io.BytesIO` or a temp file before sending.
3. Set `allow_redirects=False`, inspect `resp.headers['Location']`, recreate the generator, and resend manually.
4. For 307/308-heavy APIs, check whether the API client library offers a native retry/redirect mechanism that re-creates the body.

Example fix

# before
def gen():
    for chunk in produce_chunks():
        yield chunk
requests.post('http://api.example.com/upload', data=gen())
# after
import io
buf = io.BytesIO(b''.join(produce_chunks()))
requests.post('https://api.example.com/upload', data=buf)

def body_is_rewindable(body):
    return isinstance(body, (bytes, str)) or (hasattr(body, 'seek') and hasattr(body, 'tell'))

try:
    resp = requests.post(url, data=body_stream)
except requests.exceptions.UnrewindableBodyError:
    # body has no usable seek/tell — cannot replay for the redirect
    resp = requests.post(url, data=body_stream_factory(), allow_redirects=False)

When it happens

Trigger: Redirected POST/PUT where the body is a generator (`data=my_generator()`), an iterator for chunked uploads, or any object without `seek`/`tell`; or a file-like object whose `tell()` raised during `prepare_body`, leaving `_body_position` as a non-integer sentinel.

Common situations: Chunked uploads using generators to APIs that issue http→https or trailing-slash redirects; load-balancer or auth-gateway redirects in front of upload endpoints; wrapping compression/encryption generators around file uploads.

Related errors

• An error occurred when rewinding request body for redirect.
• Streamed bodies and files are mutually exclusive.
• chunk_size must be an int, it is instead a {type(chunk_size)
• The content for this response was already consumed
• Exceeded {self.max_redirects} redirects.

AI-assisted analysis of psf/requests@414f0513c3 (2026-07-31). Data as JSON: /data/errors/e35d8ce52f5ac8c3.json. Report an issue: GitHub ↗.