aiohttp `trace_request_ctx` type is too restrictive (Fix)

The Fix

Widened the type of the `trace_request_ctx` parameter of `ClientSession.request` and friends.

Based on closed aio-libs/aiohttp issue #9397 · PR/commit linked

Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.

Open PR/Commit

@@ -0,0 +1,3 @@
@@ -0,0 +1,3 @@
+Widened the type of the ``trace_request_ctx`` parameter of
+:meth:`ClientSession.request() <aiohttp.ClientSession.request>` and friends
+-- by :user:`layday`.

fix.md

Option A — Apply the official fix\nWidened the type of the `trace_request_ctx` parameter of `ClientSession.request` and friends.\nWhen NOT to use: This fix is not suitable if strict type enforcement is required for `trace_request_ctx`.\n\n

Why This Fix Works in Production

Trigger: `trace_request_ctx` type is too restrictive
Mechanism: The `trace_request_ctx` parameter was incorrectly restricted to only accept `Mapping[str, str]` types

Production impact:

If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

The `trace_request_ctx` parameter was incorrectly restricted to only accept `Mapping[str, str]` types
Production symptom (often without a traceback): `trace_request_ctx` type is too restrictive

Proof / Evidence

GitHub issue: #9397
Fix PR: https://github.com/aio-libs/aiohttp/pull/9398
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.60
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.80

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“### Describe the bug As of https://github.com/aio-libs/aiohttp/pull/8620, the request method's trace_request_ctx parameter is typed as taking a Mapping[str, str]. A value of str seems like an odd restriction to impose and other types are us”

Issue thread · issue description · source

Failure Signature (Search String)

`trace_request_ctx` type is too restrictive
```python-traceback

Copy-friendly signature

signature.txt

Failure Signature
-----------------
`trace_request_ctx` type is too restrictive
```python-traceback

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
`trace_request_ctx` type is too restrictive
```python-traceback

What Broke

Users encountered type errors when passing non-string values to `trace_request_ctx`.

Why It Broke

The `trace_request_ctx` parameter was incorrectly restricted to only accept `Mapping[str, str]` types

Fix Options (Details)

Option A — Apply the official fix

Widened the type of the `trace_request_ctx` parameter of `ClientSession.request` and friends.

When NOT to use: This fix is not suitable if strict type enforcement is required for `trace_request_ctx`.

Fix reference: https://github.com/aio-libs/aiohttp/pull/9398

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

This fix is not suitable if strict type enforcement is required for `trace_request_ctx`.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
Pin production dependencies and upgrade only with a reproducible test that hits the failing path.

Related Issues

No related fixes found.

Cluster: aiohttp:configuration-error All hubs All clusters

Related clusters: Data consistency Race condition Auth

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.