{"record":{"id":"3c1134d655637aad","repo":"pola-rs/polars","slug":"encoding-must-be-one-of-hex-base64-got-3c1134","errorCode":null,"errorMessage":"`encoding` must be one of {'hex', 'base64'}, got {encoding!r}","messagePattern":"`encoding` must be one of (.+?), got (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/expr/string.py","lineNumber":1433,"sourceCode":"        >>> df.with_columns(pl.col(\"color\").str.decode(\"hex\").alias(\"decoded\"))\n        shape: (3, 2)\n        ┌────────┬─────────────────┐\n        │ color  ┆ decoded         │\n        │ ---    ┆ ---             │\n        │ str    ┆ binary          │\n        ╞════════╪═════════════════╡\n        │ 000000 ┆ b\"\\x00\\x00\\x00\" │\n        │ ffff00 ┆ b\"\\xff\\xff\\x00\" │\n        │ 0000ff ┆ b\"\\x00\\x00\\xff\" │\n        └────────┴─────────────────┘\n        \"\"\"\n        if encoding == \"hex\":\n            return wrap_expr(self._pyexpr.str_hex_decode(strict))\n        elif encoding == \"base64\":\n            return wrap_expr(self._pyexpr.str_base64_decode(strict))\n        else:\n            msg = f\"`encoding` must be one of {{'hex', 'base64'}}, got {encoding!r}\"\n            raise ValueError(msg)\n\n    def encode(self, encoding: TransferEncoding) -> Expr:\n        \"\"\"\n        Encode values using the provided encoding.\n\n        Parameters\n        ----------\n        encoding : {'hex', 'base64'}\n            The encoding to use.\n\n        .. engine-support:: in-memory, streaming, distributed\n\n        Returns\n        -------\n        Expr\n            Expression of data type :class:`String`.\n\n        Examples","sourceCodeStart":1415,"sourceCodeEnd":1451,"githubUrl":"https://github.com/pola-rs/polars/blob/5d8ebabf11caea54a5c29178a64a058762f49766/py-polars/src/polars/expr/string.py#L1415-L1451","documentation":"Raised by `Expr.str.decode(encoding, strict=...)` when `encoding` is neither 'hex' nor 'base64'. Despite the name, this method only reverses binary-to-text transfer encodings — it is not a general character-set decoder like Python's `bytes.decode`. The check is a plain Python if/elif that falls through to ValueError.","triggerScenarios":"`pl.col(\"s\").str.decode(\"utf-8\")`, `\"ascii\"`, `\"latin-1\"`, or a case variant like \"Hex\"; treating hex/base64-decoded output as text instead of `Binary` data.","commonSituations":"Developers assuming str.decode mirrors Python's codecs module; processing base64 blobs from APIs and reaching for the wrong encoding name; forgetting that the output is a Binary column that still needs further handling to become text.","solutions":["Use 'hex' or 'base64' — these are the only supported encodings.","For character-set decoding of binary data, use `map_elements` with Python's codecs, accepting the performance cost.","If the decoded bytes are UTF-8 text, chain with a cast: decode to Binary then `.cast(pl.String)` via `map_elements(bytes.decode, ...)`.","Double-check case: 'Hex' with a capital H is rejected."],"exampleFix":"# before\npl.col(\"s\").str.decode(\"utf-8\")\n\n# after\npl.col(\"s\").str.decode(\"base64\")  # only 'hex' and 'base64' exist","handlingStrategy":"validation","validationCode":"TRANSFER_ENCODINGS = {\"hex\", \"base64\"}\nif encoding not in TRANSFER_ENCODINGS:\n    raise ValueError(\n        f\"str.decode supports only {sorted(TRANSFER_ENCODINGS)}, got {encoding!r}; \"\n        \"for charset decoding use map_elements with codecs\"\n    )\nout = pl.col(c).str.decode(encoding, strict=strict)","typeGuard":"from typing import Literal, TypeGuard\n\nTransferEncoding = Literal[\"hex\", \"base64\"]\n\ndef is_transfer_encoding(x: object) -> TypeGuard[TransferEncoding]:\n    return isinstance(x, str) and x in (\"hex\", \"base64\")","tryCatchPattern":null,"preventionTips":["Remember str.decode output is Binary, not String — plan the next step of the pipeline accordingly.","Keep codec names ('utf-8' etc.) out of str.decode/encode; those belong to map_elements with Python codecs.","Validate encoding strings from config against the fixed set at load time."],"tags":["polars","string","encoding","base64","invalid-argument-value"],"backgroundTag":"unsupported-encoding","analyzedSha":"5d8ebabf11caea54a5c29178a64a058762f49766","analyzedAt":"2026-08-19T12:15:06.350Z","contentChangedAt":"2026-08-19T12:15:06.350Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}