{"id":"8863799028e3744a","repo":"encode/httpx","slug":"exc","errorCode":null,"errorMessage":"{exc}","messagePattern":"\\{exc\\}","errorType":"exception","errorClass":"DecodingError","httpStatus":null,"severity":"error","filePath":"httpx/_decoders.py","lineNumber":76,"sourceCode":"    Handle 'deflate' decoding.\n\n    See: https://stackoverflow.com/questions/1838699\n    \"\"\"\n\n    def __init__(self) -> None:\n        self.first_attempt = True\n        self.decompressor = zlib.decompressobj()\n\n    def decode(self, data: bytes) -> bytes:\n        was_first_attempt = self.first_attempt\n        self.first_attempt = False\n        try:\n            return self.decompressor.decompress(data)\n        except zlib.error as exc:\n            if was_first_attempt:\n                self.decompressor = zlib.decompressobj(-zlib.MAX_WBITS)\n                return self.decode(data)\n            raise DecodingError(str(exc)) from exc\n\n    def flush(self) -> bytes:\n        try:\n            return self.decompressor.flush()\n        except zlib.error as exc:  # pragma: no cover\n            raise DecodingError(str(exc)) from exc\n\n\nclass GZipDecoder(ContentDecoder):\n    \"\"\"\n    Handle 'gzip' decoding.\n\n    See: https://stackoverflow.com/questions/1838699\n    \"\"\"\n\n    def __init__(self) -> None:\n        self.decompressor = zlib.decompressobj(zlib.MAX_WBITS | 16)\n","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/encode/httpx/blob/b5addb64f0161ff6bfe94c124ef76f6a1fba5254/httpx/_decoders.py#L58-L94","documentation":"DecodingError raised inside DeflateDecoder.decode when zlib.decompress fails on the second (raw deflate) attempt. httpx first tries zlib with default headers, then if that fails retries with -MAX_WBITS (raw deflate); a second failure bubbles up as DecodingError wrapping the underlying zlib.error. This indicates the response body declared 'deflate' Content-Encoding but is not valid zlib or raw-deflate data.","triggerScenarios":"Server sending 'Content-Encoding: deflate' but shipping actually-gzip or plain bytes; truncated deflate body (network drop, proxy truncation); server using an undocumented deflate variant; misconfigured origin returning an error page (HTML) with a stale deflate header.","commonSituations":"Upstream mislabeling encoding; CDN/proxy re-encoding body but not header; connection drops leaving a partial body; some legacy servers serving deflate of gzipped data; testing with a mock that sets the header but not the encoding.","solutions":["Reproduce with curl --compressed to confirm the server is genuinely sending bad deflate; file a bug upstream.","Strip Content-Encoding handling by reading raw bytes: iterate resp.iter_raw() instead of resp.iter_bytes().","Disable transparent decoding by removing 'deflate' from client acceptance (set Accept-Encoding: identity).","If the body is actually gzip, ask the server to send correct headers or pre-decode manually with gzip on resp.iter_raw()."],"exampleFix":"// before\nresp = client.get(url)  # server mislabels deflate\nbody = resp.content  # DecodingError\n// after\nresp = client.get(url, headers={'Accept-Encoding': 'identity'})\nbody = resp.content  # raw bytes; decode manually if needed","handlingStrategy":"fallback","validationCode":"# Before issuing, opt out of deflate if you cannot trust the server\nheaders = {'Accept-Encoding': 'gzip, identity'}  # no deflate\nresp = client.get(url, headers=headers)","typeGuard":null,"tryCatchPattern":"try:\n    body = resp.content\nexcept httpx.DecodingError:\n    # server mislabeled deflate; read raw and decode manually or skip\n    resp = client.get(url, headers={'Accept-Encoding': 'identity'})\n    body = resp.content","preventionTips":["Pin Accept-Encoding to encodings you know the server emits correctly.","Log Content-Encoding vs actual bytes when debugging decoding errors.","Keep a retry path that requests identity encoding.","Validate server behaviour with curl --compressed before coding against it."],"tags":["decoding","deflate","content-encoding","server-error"],"analyzedSha":"b5addb64f0161ff6bfe94c124ef76f6a1fba5254","analyzedAt":"2026-08-04T19:32:56.768Z","schemaVersion":2}