encode/httpx · error · RuntimeError

Attempted to send an async request with a sync Client instan

Error message

Attempted to send an async request with a sync Client instance.

What it means

Raised as RuntimeError by sync Client._send_single_request when request.stream is not a SyncByteStream. The request body was built from an async iterable/generator, which cannot be driven by a synchronous client.

Source

Thrown at httpx/_client.py:1009

                if follow_redirects:
                    response.read()
                else:
                    response.next_request = request
                    return response

            except BaseException as exc:
                response.close()
                raise exc

    def _send_single_request(self, request: Request) -> Response:
        """
        Sends a single request, without handling any redirections.
        """
        transport = self._transport_for_url(request.url)
        start = time.perf_counter()

        if not isinstance(request.stream, SyncByteStream):
            raise RuntimeError(
                "Attempted to send an async request with a sync Client instance."
            )

        with request_context(request=request):
            response = transport.handle_request(request)

        assert isinstance(response.stream, SyncByteStream)

        response.request = request
        response.stream = BoundSyncStream(
            response.stream, response=response, start=start
        )
        self.cookies.extract_cookies(response)
        response.default_encoding = self._default_encoding

        logger.info(
            'HTTP Request: %s %s "%s %d %s"',
            request.method,

View on GitHub (pinned to b5addb64f0)

Solutions

1. Use httpx.AsyncClient to send requests whose body is an async iterable.
2. If you must use the sync Client, supply a sync iterable/bytes as content instead.

Example fix

// before
async def gen(): yield b"data"
httpx.Client().send(httpx.Request("POST", url, content=gen()))  # RuntimeError
// after
# use AsyncClient for async content
async with httpx.AsyncClient() as c:
    await c.post(url, content=gen())

import inspect, collections.abc as abc

def is_sync_content(content) -> bool:
    if isinstance(content, (bytes, str)):
        return True
    if isinstance(content, abc.AsyncIterable):
        return False
    return True  # plain iterable

# for sync Client, ensure content is NOT an async iterable
assert is_sync_content(content), "async content cannot be used with sync Client"

import collections.abc as abc

def is_async_content(content) -> bool:
    return isinstance(content, abc.AsyncIterable)

try:
    client.send(req)
except RuntimeError as exc:
    if "async request with a sync Client" in str(exc):
        raise RuntimeError("Use httpx.AsyncClient for async-iterable content") from exc
    raise

When it happens

Trigger: Constructing an httpx.Request with an async byte generator as content (e.g. content=<async generator>) and sending it through the sync client.send()/client.request().

Common situations: Mixing an async content source (async def/async generator yielding bytes) with a synchronous Client; copying a request built for async use into sync code.

Related errors

• Attempted to send a sync request with an AsyncClient instanc
• Attempted to call a sync iterator on an async stream.
• Attempted to call a sync close on an async stream.
• Attempted to call an async iterator on a sync stream.
• Attempted to call an async close on a sync stream.

AI-assisted analysis of encode/httpx@b5addb64f0 (2026-08-04). Data as JSON: /data/errors/baa38231c98255c2.json. Report an issue: GitHub.