aio-libs/aiohttp · error · ContentEncodingError

Can not decode content-encoding: zstandard (zstd). Please…

Error message

Can not decode content-encoding: zstandard (zstd). Please install `backports.zstd`

What it means

Raised as ContentEncodingError when a response body declares 'Content-Encoding: zstd' (zstandard) but the optional zstd library is not installed (HAS_ZSTD is False). DeflateBuffer.__init__ checks the flag before constructing a ZSTDDecompressor and raises this install hint. Note the message references 'backports.zstd' as the install target.

Solutions

Install the zstd binding the project expects: 'pip install backports.zstd' (or the package indicated by aiohttp's compression_utils).
Or install aiohttp with the zstd extra if available.
If you cannot install it, disable auto-decompression: ClientSession(..., auto_decompress=False).
Remove 'zstd' from your Accept-Encoding header so the server does not negotiate it.

Example fix

# before
pip install aiohttp
session = aiohttp.ClientSession()  # server sends zstd -> error

# after
pip install backports.zstd
# or
session = aiohttp.ClientSession(headers={'Accept-Encoding': 'gzip, deflate, br'})

Defensive patterns

Strategy: fallback

Validate before calling

try:
    import zstandard  # or backports.zstd depending on aiohttp version
    HAS_ZSTD = True
except ImportError:
    HAS_ZSTD = False

def accept_encoding_for_zstd(want_zstd: bool = True) -> str:
    base = 'gzip, deflate'
    if want_zstd and HAS_ZSTD:
        return base + ', zstd'
    return base

Try / catch

from aiohttp.http_exceptions import ContentEncodingError
import aiohttp

async def get_robust(url):
    try:
        async with aiohttp.ClientSession() as s:
            async with s.get(url) as r:
                return await r.read()
    except ContentEncodingError as e:
        if 'zstd' in str(e):
            async with aiohttp.ClientSession(headers={'Accept-Encoding': 'gzip, deflate'}) as s:
                async with s.get(url) as r:
                    return await r.read()
        raise

Prevention

Install the zstd binding (pip install backports.zstd) in the image.
Only advertise 'zstd' in Accept-Encoding when the lib is present.
Disable auto_decompress if you want raw bytes.
Pin optional compression deps in CI and production.

When it happens

Trigger: The server returns 'Content-Encoding: zstd' and auto_decompress is enabled (default), but the zstd (backports.zstd / zstandard) package is not importable, so HAS_ZSTD is False.

Common situations: A deployment without the zstd optional dependency; a slim Docker image; CI missing the extra; a server that starts using zstd after a CDN/upstream change; older aiohttp versions where zstd support is new and the runtime lacks the lib.

Related errors

AI-assisted analysis of aio-libs/aiohttp@d041d4d0fd (2026-08-11). Data as JSON: /api/errors/1175ad5703df7ade. Report an issue: GitHub.

Appendix: source

Thrown at aiohttp/http_parser.py:1156

        max_decompress_size: int = DEFAULT_CHUNK_SIZE,
    ) -> None:
        self.out = out
        self.size = 0
        out.total_compressed_bytes = self.size
        self.encoding = encoding
        self._started_decoding = False

        self.decompressor: BrotliDecompressor | ZLibDecompressor | ZSTDDecompressor
        if encoding == "br":
            if not HAS_BROTLI:
                raise ContentEncodingError(
                    "Can not decode content-encoding: brotli (br). "
                    "Please install `Brotli`"
                )
            self.decompressor = BrotliDecompressor()
        elif encoding == "zstd":
            if not HAS_ZSTD:
                raise ContentEncodingError(
                    "Can not decode content-encoding: zstandard (zstd). "
                    "Please install `backports.zstd`"
                )
            self.decompressor = ZSTDDecompressor()
        else:
            self.decompressor = ZLibDecompressor(encoding=encoding)

        self._max_decompress_size = max_decompress_size

    def set_exception(
        self,
        exc: type[BaseException] | BaseException,
        exc_cause: BaseException = _EXC_SENTINEL,
    ) -> None:
        set_exception(self.out, exc, exc_cause)

    def feed_data(self, chunk: bytes) -> bool:
        """Return True if more data is available and this method should be called again with b""."""

View on GitHub (pinned to d041d4d0fd)