Fix: Improve error message for invalid data parameter with AsyncClient

[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.