{"record":{"id":"1398d4068b9ca5f3","repo":"pypa/pip","slug":"unsupported-error-handling-errors","errorCode":null,"errorMessage":"Unsupported error handling \"{errors}\"","messagePattern":"Unsupported error handling \"(.+?)\"","errorType":"exception","errorClass":"IDNAError","httpStatus":null,"severity":"error","filePath":"src/pip/_vendor/idna/codec.py","lineNumber":20,"sourceCode":"from typing import Any, Optional\n\nfrom .core import IDNAError, _unicode_dots_re, alabel, decode, encode, ulabel\n\n\nclass Codec(codecs.Codec):\n    \"\"\"Stateless IDNA 2008 codec.\n\n    Implements the :class:`codecs.Codec` protocol so that the whole-domain\n    encoder (:func:`idna.encode`) and decoder (:func:`idna.decode`) are\n    accessible through the standard codec machinery as ``\"idna2008\"``.\n\n    Only the ``\"strict\"`` error handler is supported; any other handler\n    raises :exc:`~idna.IDNAError`.\n    \"\"\"\n\n    def encode(self, data: str, errors: str = \"strict\") -> tuple[bytes, int]:  # ty: ignore[invalid-method-override]\n        if errors != \"strict\":\n            raise IDNAError(f'Unsupported error handling \"{errors}\"')\n\n        if not data:\n            return b\"\", 0\n\n        return encode(data), len(data)\n\n    def decode(self, data: bytes, errors: str = \"strict\") -> tuple[str, int]:  # ty: ignore[invalid-method-override]\n        if errors != \"strict\":\n            raise IDNAError(f'Unsupported error handling \"{errors}\"')\n\n        if not data:\n            return \"\", 0\n\n        return decode(data), len(data)\n\n\nclass IncrementalEncoder(codecs.BufferedIncrementalEncoder):\n    \"\"\"Incremental IDNA 2008 encoder.","sourceCodeStart":2,"sourceCodeEnd":38,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_vendor/idna/codec.py#L2-L38","documentation":"Raised by idna's Codec.encode (the stateless codec used by str.encode('idna2008')) when the errors parameter is anything other than 'strict'. The IDNA 2008 codec intentionally supports only strict error handling — all encoding failures must surface as IDNAError — so passing 'ignore', 'replace', 'backslashreplace', etc. is rejected immediately.","triggerScenarios":"Calling 'some-string'.encode('idna2008', errors='ignore') or invoking the codec's encode method with a non-strict errors argument. Also triggered indirectly by libraries that pass a default errors handler to all codecs.","commonSituations":"A URL-processing library generically passes errors='replace' to all registered codecs; developer assumes idna works like utf-8 with lenient error modes; code copied from a utf-8 example.","solutions":["Omit the errors argument (it defaults to 'strict') or explicitly pass errors='strict'.","If you need lenient handling, validate/normalize the domain before encoding and handle IDNAError yourself.","Use idna.encode(domain) directly instead of the codec machinery if you need the full API."],"exampleFix":"# before\nencoded = 'café.com'.encode('idna2008', errors='ignore')  # raises\n\n# after\nencoded = 'café.com'.encode('idna2008')  # strict by default","handlingStrategy":"validation","validationCode":"def safe_idna_encode(domain):\n    return domain.encode('idna2008')  # errors defaults to 'strict'","typeGuard":"def is_valid_errors_value(errors: str) -> bool:\n    return errors == 'strict'","tryCatchPattern":"from idna.core import IDNAError\ntry:\n    encoded = domain.encode('idna2008')\nexcept IDNAError:\n    encoded = domain.encode('ascii', 'ignore')  # fallback for display","preventionTips":["Never pass errors= to the idna2008 codec — it only supports strict.","If a framework passes errors generically, register a wrapper that strips it for idna2008.","Handle IDNAError at the call site for custom fallback behavior."],"tags":["idna","codec","encoding","validation"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}