aiohttp Can not decode content-encoding: zstd (Fix)

The Fix

Fix zstd decompression for chunked zstd response, preventing crashes when decoding zstd streams.

Based on closed aio-libs/aiohttp issue #11635 · 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%.

Jump to Verify Open PR/Commit

@@ -0,0 +1 @@
@@ -0,0 +1 @@
+Switched to `backports.zstd` for Python <3.14 and fixed zstd decompression for chunked zstd streams -- by :user:`ZhaoMJ`.
diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index b64d99fb632..84692200b6e 100644

repro.py

import asyncio
import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get("https://hoyo-codes.seria.moe/codes?game=genshin") as resp:
            await resp.json()


asyncio.run(main())

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Apply the official fix\nFix zstd decompression for chunked zstd response, preventing crashes when decoding zstd streams.\nWhen NOT to use: Do not use if it changes public behavior or if the failure cannot be reproduced.\n\n

Why This Fix Works in Production

Trigger: chunk = self.decompressor.decompress_sync(chunk)
Mechanism: The aiohttp library fails to decode zstd compressed responses due to missing support for the zstandard library

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 aiohttp library fails to decode zstd compressed responses due to missing support for the zstandard library
Surfaces as: c:/Users/Seria/Documents/GitHub/hoyo-buddy/test.py

Proof / Evidence

GitHub issue: #11635
Fix PR: https://github.com/aio-libs/aiohttp/pull/11623
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.37

Discussion

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

Jump to Sources Open on GitHub

“Let me know if that's not resolved the problem.”

@Dreamsorcerer · 2025-10-17 · confirmation · source

“We'll push a .1 release by the end of the week. Note that you'll need to install backports.zstd instead from that release.”

@Dreamsorcerer · 2025-10-13 · source

“Same issue that's fixed by https://github.com/aio-libs/aiohttp/pull/11623”

@ZhaoMJ · 2025-10-13 · source

Failure Signature (Search String)

chunk = self.decompressor.decompress_sync(chunk)

Error Message

Stack trace

error.txt

Error Message
-------------
c:/Users/Seria/Documents/GitHub/hoyo-buddy/test.py
Traceback (most recent call last):
  File "C:\Users\Seria\Documents\GitHub\hoyo-buddy\.venv\Lib\site-packages\aiohttp\http_parser.py", line 1018, in feed_data      
    chunk = self.decompressor.decompress_sync(chunk)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\Seria\Documents\GitHub\hoyo-buddy\.venv\Lib\site-packages\aiohttp\compression_utils.py", line 306, in decompress_sync
    return self._obj.decompress(data)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
zstandard.backend_c.ZstdError: could not determine content size in frame header

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "aiohttp/_http_parser.pyx", line 761, in aiohttp._http_parser.cb_on_body
    pyparser._payload.feed_data(body, length)
  File "C:\Users\Seria\Documents\GitHub\hoyo-buddy\.venv\Lib\site-packages\aiohttp\http_parser.py", line 1020, in feed_data      
    raise ContentEncodingError(
aiohttp.http_exceptions.ContentEncodingError: 400, message:
  Can not decode content-encoding: zstd

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "c:\Users\Seria\Documents\GitHub\hoyo-buddy\test.py", line 11, in <module>
    asyncio.run(main())
  File "C:\Users\Seria\AppData\Roaming\uv\python\cpython-3.12.10-windows-x86_64-no
... (truncated) ...

Minimal Reproduction

repro.py

import asyncio
import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get("https://hoyo-codes.seria.moe/codes?game=genshin") as resp:
            await resp.json()


asyncio.run(main())

What Broke

Users experience crashes when attempting to decode zstd compressed JSON responses.

Why It Broke

The aiohttp library fails to decode zstd compressed responses due to missing support for the zstandard library

Fix Options (Details)

Option A — Apply the official fix

Fix zstd decompression for chunked zstd response, preventing crashes when decoding zstd streams.

When NOT to use: Do not use if it changes public behavior or if the failure cannot be reproduced.

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

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

When NOT to Use This Fix

Do not use if it changes public behavior or if the failure cannot be reproduced.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

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.