{"record":{"id":"b1ad88480fbd8f59","repo":"aio-libs/aiohttp","slug":"unknown-content-transfer-encoding-te-encoding","errorCode":null,"errorMessage":"unknown content transfer encoding: {te_encoding}","messagePattern":"unknown content transfer encoding: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"aiohttp/multipart.py","lineNumber":1045,"sourceCode":"                not {CONTENT_ENCODING, CONTENT_LENGTH, CONTENT_TRANSFER_ENCODING}\n                & payload.headers.keys()\n            )\n            # Set default Content-Disposition in case user doesn't create one\n            if CONTENT_DISPOSITION not in payload.headers:\n                name = f\"section-{len(self._parts)}\"\n                payload.set_content_disposition(\"form-data\", name=name)\n        else:\n            # compression\n            encoding = payload.headers.get(CONTENT_ENCODING, \"\").lower()\n            if encoding and encoding not in (\"deflate\", \"gzip\", \"identity\"):\n                raise RuntimeError(f\"unknown content encoding: {encoding}\")\n            if encoding == \"identity\":\n                encoding = None\n\n            # te encoding\n            te_encoding = payload.headers.get(CONTENT_TRANSFER_ENCODING, \"\").lower()\n            if te_encoding not in (\"\", \"base64\", \"quoted-printable\", \"binary\"):\n                raise RuntimeError(f\"unknown content transfer encoding: {te_encoding}\")\n            if te_encoding == \"binary\":\n                te_encoding = None\n\n            # size\n            size = payload.size\n            if size is not None and not (encoding or te_encoding):\n                payload.headers[CONTENT_LENGTH] = str(size)\n\n        self._parts.append((payload, encoding, te_encoding))  # type: ignore[arg-type]\n        return payload\n\n    def append_json(\n        self, obj: Any, headers: Mapping[str, str] | None = None\n    ) -> Payload:\n        \"\"\"Helper to append JSON part.\"\"\"\n        if headers is None:\n            headers = CIMultiDict()\n","sourceCodeStart":1027,"sourceCodeEnd":1063,"githubUrl":"https://github.com/aio-libs/aiohttp/blob/d041d4d0fd48c3f0832084d33be16cf1c4835f85/aiohttp/multipart.py#L1027-L1063","documentation":"Raised by MultipartWriter when a payload being appended carries a Content-Transfer-Encoding header whose value is not one of the allowed MIME transfer encodings. aiohttp only understands '', 'base64', 'quoted-printable', and 'binary' so it refuses to serialize a part it cannot correctly encode on the wire. The check exists because multipart bodies must be encoded deterministically and an unknown transfer encoding would produce a corrupt, undecodable message.","triggerScenarios":"Calling MultipartWriter.append(payload) (or append_json/append_form with pre-set headers) where payload.headers['Content-Transfer-Encoding'] is set to a value like '7bit', '8bit', 'uuencode', 'x-uuencode', or '16bit'. Also triggered by copying headers verbatim from an inbound email-style MIME message onto an outbound part.","commonSituations":"Porting email (email.mime) code to aiohttp multipart, where 7bit/8bit are common defaults; forwarding headers from a parsed incoming multipart request without filtering; setting the header manually from user input or config.","solutions":["Remove the Content-Transfer-Encoding header from the payload before appending and let aiohttp manage encoding (delete payload.headers[CONTENT_TRANSFER_ENCODING]).","If you must set it, use one of 'base64', 'quoted-printable', or 'binary' (note 'binary' is internally normalized to None).","Sanitize/normalize the header value to lowercase and validate against the allowed set before calling append()."],"exampleFix":"# before\npayload.headers['Content-Transfer-Encoding'] = '7bit'\nwriter.append(payload)\n\n# after\ndel payload.headers['Content-Transfer-Encoding']  # let aiohttp decide\nwriter.append(payload)","handlingStrategy":"validation","validationCode":"ALLOWED_TE = {'', 'base64', 'quoted-printable', 'binary'}\nte = payload.headers.get('Content-Transfer-Encoding', '').lower()\nif te not in ALLOWED_TE:\n    payload.headers.pop('Content-Transfer-Encoding', None)\nwriter.append(payload)","typeGuard":"def is_supported_te(headers: multidict.CIMultiDict) -> bool:\n    return headers.get('Content-Transfer-Encoding', '').lower() in {'', 'base64', 'quoted-printable', 'binary'}","tryCatchPattern":"try:\n    writer.append(payload)\nexcept RuntimeError as e:\n    if 'unknown content transfer encoding' in str(e):\n        payload.headers.pop('Content-Transfer-Encoding', None)\n        writer.append(payload)\n    else:\n        raise","preventionTips":["Never copy raw MIME headers from inbound messages onto outbound multipart parts.","Let MultipartWriter manage Content-Transfer-Encoding unless you explicitly need base64/quoted-printable.","Validate any header set from user/config data against the allowed set before appending."],"tags":["multipart","mime","headers","validation"],"backgroundTag":null,"analyzedSha":"d041d4d0fd48c3f0832084d33be16cf1c4835f85","analyzedAt":"2026-08-11T20:44:15.550Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}