[veeceey]

Summary

Fixes #3471

When AsyncClient receives invalid data like data=[{"a": "b"}] (a list of dicts), it was raising a confusing error:

RuntimeError: Attempted to send a sync request with an AsyncClient instance.

This error is misleading because the user IS using an async client correctly - the actual problem is passing invalid data.

With this fix, both sync and async clients now raise a clear error immediately:

TypeError: Expected bytes-like object in 'data' sequence, got dict. Use 'json=' for JSON data or 'data={...}' for form data.

Changes

• Added validation in encode_request() to check if data is a list/tuple containing non-bytes objects
• Raises TypeError with helpful error message directing users to correct alternatives (json= or data={...})
• Added regression tests

Test Plan

Before this fix:

async_client = httpx.AsyncClient()
await async_client.request("POST", "/post", data=[{"a": "b"}])
# RuntimeError: Attempted to send a sync request with an AsyncClient instance.

After this fix:

async_client = httpx.AsyncClient()
await async_client.request("POST", "/post", data=[{"a": "b"}])
# TypeError: Expected bytes-like object in 'data' sequence, got dict. Use 'json=' for JSON data or 'data={...}' for form data.

Valid use cases still work:

• ✅ data={"key": "value"} (dict for form encoding)
• ✅ data=[b"bytes", b"data"] (list of bytes)
• ✅ json={"key": "value"} (JSON encoding)

Testing

• Manual testing with both sync and async clients
• Added regression tests in tests/test_content.py
• Verified existing test cases still pass

[veeceey]

All CI passing on Python 3.9-3.13, ready for merge

[veeceey]

Friendly ping - any chance someone could take a look at this when they get a chance? Happy to make any changes if needed.

[OKAN-SOFTWARE]

I noticed two related gaps in the regression coverage.

The new validation checks list and tuple, but other iterables can still bypass it. For example, passing data=iter([{"a": "b"}]) proceeds through encode_content() and creates an IteratorByteStream. With AsyncClient, this appears to preserve the original generic error about sending a synchronous request.

Also, test_invalid_data_list_of_dicts_async() currently constructs an httpx.Request directly. Although the test is declared asynchronous, it never exercises AsyncClient, which is the behavior reported in #3471.

Could we add a regression test that actually calls AsyncClient.post() with invalid data, including a non-list iterable?

This would verify that the improved diagnostic is raised through the original failure path and help prevent the same issue from surviving for other iterable inputs.