{"id":"88eb119a6a61686e","repo":"aio-libs/aiohttp","slug":"the-zstd-decompression-is-not-available-please-in","errorCode":null,"errorMessage":"The zstd decompression is not available. Please install `backports.zstd` module","messagePattern":"The zstd decompression is not available\\. Please install `backports\\.zstd` module","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"aiohttp/compression_utils.py","lineNumber":394,"sourceCode":"    def flush(self) -> bytes:\n        \"\"\"Flush the decompressor.\"\"\"\n        if hasattr(self._obj, \"flush\"):\n            return cast(bytes, self._obj.flush())\n        return b\"\"\n\n    @property\n    def data_available(self) -> bool:\n        return not self._obj.is_finished() and not self._last_empty\n\n\nclass ZSTDDecompressor(DecompressionBaseHandler):\n    def __init__(\n        self,\n        executor: Executor | None = None,\n        max_sync_chunk_size: int | None = MAX_SYNC_CHUNK_SIZE,\n    ) -> None:\n        if not HAS_ZSTD:\n            raise RuntimeError(\n                \"The zstd decompression is not available. \"\n                \"Please install `backports.zstd` module\"\n            )\n        self._obj = ZstdDecompressor()\n        self._pending_unused_data: bytes | None = None\n        super().__init__(executor=executor, max_sync_chunk_size=max_sync_chunk_size)\n\n    def decompress_sync(\n        self, data: bytes, max_length: int = ZLIB_MAX_LENGTH_UNLIMITED\n    ) -> bytes:\n        # zstd uses -1 for unlimited, while zlib uses 0 for unlimited\n        # Convert the zlib convention (0=unlimited) to zstd convention (-1=unlimited)\n        zstd_max_length = (\n            ZSTD_MAX_LENGTH_UNLIMITED\n            if max_length == ZLIB_MAX_LENGTH_UNLIMITED\n            else max_length\n        )\n        if self._pending_unused_data is not None:","sourceCodeStart":376,"sourceCodeEnd":412,"githubUrl":"https://github.com/aio-libs/aiohttp/blob/c0ef574e29109210e96e652771ae4e7b88615fa4/aiohttp/compression_utils.py#L376-L412","documentation":"Raised when constructing ZSTDDecompressor while neither the stdlib `zstandard`/`zstd` module nor the `backports.zstd` fallback is importable (HAS_ZSTD is False). It fires the first time aiohttp tries to decode a response with `Content-Encoding: zstd`. The message recommends `backports.zstd` specifically because that is what the import guard looks for.","triggerScenarios":"Server returns `Content-Encoding: zstd` and the client environment lacks zstd support, then the response body is read and ZSTDDecompressor is instantiated.","commonSituations":"CDN/server upgraded to advertise zstd but the client image lacks the dep. Older Python (<3.14) without stdlib zstd and no backport installed. Cached environments where the package was removed by a cleanup step.","solutions":["Install the codec: `pip install backports.zstd` (or use Python 3.14+ which ships zstdlib).","Disable zstd negotiation by setting `Accept-Encoding: gzip, deflate, br` so the server never picks zstd.","Verify the install in CI with `python -c \"import zstandard; print(zstandard.__version__)\"`."],"exampleFix":"# before\n# zstd not importable -> RuntimeError on resp.text()\n# after\n# requirements.txt\nbackports.zstd>=1.0","handlingStrategy":"validation","validationCode":"def zstd_available() -> bool:\n    try:\n        import zstandard  # noqa: F401\n        return True\n    except ImportError:\n        try:\n            import backports.zstd  # noqa: F401\n            return True\n        except ImportError:\n            return False","typeGuard":null,"tryCatchPattern":"try:\n    body = await resp.read()\nexcept RuntimeError as e:\n    if 'zstd' in str(e).lower():\n        # retry without 'zstd' in Accept-Encoding\n        ...\n    raise","preventionTips":["Pin `backports.zstd` in requirements or run on Python 3.14+.","Validate optional-dep presence in CI with `python -c \"import zstandard\"`.","Strip 'zstd' from Accept-Encoding when you cannot guarantee the codec is installed."],"tags":["compression","zstd","missing-dependency","response"],"analyzedSha":"c0ef574e29109210e96e652771ae4e7b88615fa4","analyzedAt":"2026-08-04T19:51:05.467Z","schemaVersion":2}