{"record":{"id":"1175ad5703df7ade","repo":"aio-libs/aiohttp","slug":"can-not-decode-content-encoding-zstandard-zstd","errorCode":null,"errorMessage":"Can not decode content-encoding: zstandard (zstd). Please install `backports.zstd`","messagePattern":"Can not decode content-encoding: zstandard \\(zstd\\)\\. Please install `backports\\.zstd`","errorType":"http","errorClass":"ContentEncodingError","httpStatus":400,"severity":"error","filePath":"aiohttp/http_parser.py","lineNumber":1156,"sourceCode":"        max_decompress_size: int = DEFAULT_CHUNK_SIZE,\n    ) -> None:\n        self.out = out\n        self.size = 0\n        out.total_compressed_bytes = self.size\n        self.encoding = encoding\n        self._started_decoding = False\n\n        self.decompressor: BrotliDecompressor | ZLibDecompressor | ZSTDDecompressor\n        if encoding == \"br\":\n            if not HAS_BROTLI:\n                raise ContentEncodingError(\n                    \"Can not decode content-encoding: brotli (br). \"\n                    \"Please install `Brotli`\"\n                )\n            self.decompressor = BrotliDecompressor()\n        elif encoding == \"zstd\":\n            if not HAS_ZSTD:\n                raise ContentEncodingError(\n                    \"Can not decode content-encoding: zstandard (zstd). \"\n                    \"Please install `backports.zstd`\"\n                )\n            self.decompressor = ZSTDDecompressor()\n        else:\n            self.decompressor = ZLibDecompressor(encoding=encoding)\n\n        self._max_decompress_size = max_decompress_size\n\n    def set_exception(\n        self,\n        exc: type[BaseException] | BaseException,\n        exc_cause: BaseException = _EXC_SENTINEL,\n    ) -> None:\n        set_exception(self.out, exc, exc_cause)\n\n    def feed_data(self, chunk: bytes) -> bool:\n        \"\"\"Return True if more data is available and this method should be called again with b\"\".\"\"\"","sourceCodeStart":1138,"sourceCodeEnd":1174,"githubUrl":"https://github.com/aio-libs/aiohttp/blob/d041d4d0fd48c3f0832084d33be16cf1c4835f85/aiohttp/http_parser.py#L1138-L1174","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\r\npip install aiohttp\r\nsession = aiohttp.ClientSession()  # server sends zstd -> error\r\n\r\n# after\r\npip install backports.zstd\r\n# or\r\nsession = aiohttp.ClientSession(headers={'Accept-Encoding': 'gzip, deflate, br'})","handlingStrategy":"fallback","validationCode":"try:\n    import zstandard  # or backports.zstd depending on aiohttp version\n    HAS_ZSTD = True\nexcept ImportError:\n    HAS_ZSTD = False\n\ndef accept_encoding_for_zstd(want_zstd: bool = True) -> str:\n    base = 'gzip, deflate'\n    if want_zstd and HAS_ZSTD:\n        return base + ', zstd'\n    return base","typeGuard":null,"tryCatchPattern":"from aiohttp.http_exceptions import ContentEncodingError\nimport aiohttp\n\nasync def get_robust(url):\n    try:\n        async with aiohttp.ClientSession() as s:\n            async with s.get(url) as r:\n                return await r.read()\n    except ContentEncodingError as e:\n        if 'zstd' in str(e):\n            async with aiohttp.ClientSession(headers={'Accept-Encoding': 'gzip, deflate'}) as s:\n                async with s.get(url) as r:\n                    return await r.read()\n        raise","preventionTips":["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."],"tags":["content-encoding","zstd","decompression","missing-dependency","optional-deps"],"backgroundTag":null,"analyzedSha":"d041d4d0fd48c3f0832084d33be16cf1c4835f85","analyzedAt":"2026-08-11T20:44:15.550Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}