{"record":{"id":"dfa061a4b894bbda","repo":"aio-libs/aiohttp","slug":"the-brotli-decompression-is-not-available-please","errorCode":null,"errorMessage":"The brotli decompression is not available. Please install `Brotli` module","messagePattern":"The brotli decompression is not available\\. Please install `Brotli` module","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"aiohttp/compression_utils.py","lineNumber":439,"sourceCode":"        )\n\n    @property\n    def eof(self) -> bool:\n        return self._decompressor.eof\n\n\nclass BrotliDecompressor(DecompressionBaseHandler):\n    # Supports both 'brotlipy' and 'Brotli' packages\n    # since they share an import name. The top branches\n    # are for 'brotlipy' and bottom branches for 'Brotli'\n    def __init__(\n        self,\n        executor: Executor | None = None,\n        max_sync_chunk_size: int | None = MAX_SYNC_CHUNK_SIZE,\n    ) -> None:\n        \"\"\"Decompress data using the Brotli library.\"\"\"\n        if not HAS_BROTLI:\n            raise RuntimeError(\n                \"The brotli decompression is not available. \"\n                \"Please install `Brotli` module\"\n            )\n        self._obj = brotli.Decompressor()\n        self._last_empty = False\n        super().__init__(executor=executor, max_sync_chunk_size=max_sync_chunk_size)\n\n    def decompress_sync(\n        self, data: Buffer, max_length: int = ZLIB_MAX_LENGTH_UNLIMITED\n    ) -> bytes:\n        \"\"\"Decompress the given data.\"\"\"\n        if hasattr(self._obj, \"decompress\"):\n            if max_length == ZLIB_MAX_LENGTH_UNLIMITED:\n                result = cast(bytes, self._obj.decompress(data))\n            else:\n                result = cast(bytes, self._obj.decompress(data, max_length))\n        else:\n            if max_length == ZLIB_MAX_LENGTH_UNLIMITED:","sourceCodeStart":421,"sourceCodeEnd":457,"githubUrl":"https://github.com/aio-libs/aiohttp/blob/d041d4d0fd48c3f0832084d33be16cf1c4835f85/aiohttp/compression_utils.py#L421-L457","documentation":"Raised by BrotliDecompressor.__init__ when neither the brotli nor brotlicffi module could be imported at startup (HAS_BROTLI is False). aiohttp advertises 'br' in Accept-Encoding only when brotli support is detected, but if a response still arrives as Content-Encoding: br (e.g. forced by a custom headers override, a proxy, or a stale session), the decompressor is constructed and aborts immediately. Installing the optional dependency is the supported fix.","triggerScenarios":"Server returns Content-Encoding: br but aiohttp was installed without the brotli extra; a reverse proxy rewrites responses to br regardless of Accept-Encoding; manual headers={'Accept-Encoding': 'br'} sent even though brotli is absent.","commonSituations":"Fresh pip install aiohttp without extras in a slim container; CI image missing the optional C library; pinning aiohttp to a version where the extra was renamed; brotlicffi present but import broken on the platform.","solutions":["Install the dependency: pip install Brotli (or pip install brotlicffi on PyPy/locked-down envs).","Install aiohttp with the relevant extra, e.g. pip install 'aiohttp[spdylite]' where applicable.","Stop forcing Accept-Encoding: br in custom request headers when brotli is not installed.","If you cannot add deps, configure the server/proxy to send gzip or identity instead."],"exampleFix":"# shell\n# before: aiohttp installed without brotli\npip install Brotli\n# or pin brotlicffi for environments without the C toolchain\npip install brotlicffi","handlingStrategy":"fallback","validationCode":"try:\n    import brotli  # noqa: F401\n    HAS_BROTLI = True\nexcept ImportError:\n    HAS_BROTLI = False\n\nheaders = {'Accept-Encoding': 'gzip, identity'} if not HAS_BROTLI else {'Accept-Encoding': 'gzip, br'}\nawait session.get(url, headers=headers)","typeGuard":"null","tryCatchPattern":"try:\n    data = await resp.read()\nexcept RuntimeError as exc:\n    if 'brotli' in str(exc).lower():\n        raise RuntimeError('install Brotli or drop br from Accept-Encoding') from exc\n    raise","preventionTips":["Install aiohttp with the brotli extra in deployment images.","Do not override Accept-Encoding to include br unless brotli is installed.","Pin the brotli dependency in requirements so CI matches production."],"tags":["decompression","dependency","brotli","runtime-error"],"backgroundTag":null,"analyzedSha":"d041d4d0fd48c3f0832084d33be16cf1c4835f85","analyzedAt":"2026-08-11T20:44:15.550Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}