The Fix
Added a `decode_text` parameter to `ws_connect()` and `WebSocketResponse()` that allows receiving WebSocket TEXT messages as raw bytes instead of decoded strings, improving performance with JSON parsers.
Based on closed aio-libs/aiohttp issue #11763 · 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%.
@@ -0,0 +1 @@
@@ -0,0 +1 @@
+Added ``decode_text`` parameter to :meth:`~aiohttp.ClientSession.ws_connect` and :class:`~aiohttp.web.WebSocketResponse` to receive WebSocket TEXT messages as raw bytes instead of decoded strings, enabling direct use with high-performance JSON parsers like ``orjson`` -- by :user:`bdraco`.
diff --git a/CHANGES/11764.feature.rst b/CHANGES/11764.feature.rst
new file mode 120000
Option A — Apply the official fix\nAdded a `decode_text` parameter to `ws_connect()` and `WebSocketResponse()` that allows receiving WebSocket TEXT messages as raw bytes instead of decoded strings, improving performance with JSON parsers.\nWhen NOT to use: Do not use this fix if string decoding is required for your application.\n\n
Why This Fix Works in Production
- Trigger: Managed to work it out. The actual change is about 7 lines.. and than another 100+ lines of typing :(
- Mechanism: The websocket client automatically decodes bytes to strings, causing unnecessary overhead
- 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 websocket client automatically decodes bytes to strings, causing unnecessary overhead
- Production symptom (often without a traceback): @bdraco sorry I can't trace through that library at the moment to understand the approach.
Proof / Evidence
- GitHub issue: #11763
- Fix PR: https://github.com/aio-libs/aiohttp/pull/11764
- Reproduced locally: No (not executed)
- Last verified: 2026-02-09
- Confidence: 0.70
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.69
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“> Look at how aioshelly implements this”
“TBH, I'm not sure if we want to go with https://github.com/aio-libs/aiohttp/pull/11764 or https://github.com/aio-libs/aiohttp/pull/11765”
“Look at how aioshelly implements this. Let me know if you were thinking something else”
“@bdraco sorry I can't trace through that library at the moment to understand the approach”
Failure Signature (Search String)
- Managed to work it out. The actual change is about 7 lines.. and than another 100+ lines of typing :(
Copy-friendly signature
Failure Signature
-----------------
@bdraco sorry I can't trace through that library at the moment to understand the approach.
Managed to work it out. The actual change is about 7 lines.. and than another 100+ lines of typing :(
Error Message
Signature-only (no traceback captured)
Error Message
-------------
@bdraco sorry I can't trace through that library at the moment to understand the approach.
Managed to work it out. The actual change is about 7 lines.. and than another 100+ lines of typing :(
What Broke
High-performance websocket clients experience performance degradation due to string conversion.
Why It Broke
The websocket client automatically decodes bytes to strings, causing unnecessary overhead
Fix Options (Details)
Option A — Apply the official fix
Added a `decode_text` parameter to `ws_connect()` and `WebSocketResponse()` that allows receiving WebSocket TEXT messages as raw bytes instead of decoded strings, improving performance with JSON parsers.
Fix reference: https://github.com/aio-libs/aiohttp/pull/11764
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- Do not use this fix if string decoding is required for your application.
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.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.