pola-rs/polars · error · ValueError

`encoding` must be one of

Error message

`encoding` must be one of {'hex', 'base64'}, got {encoding!r}

What it means

Expr.str.decode() only supports encoding='hex' or encoding='base64'. Any other value raises this ValueError listing the allowed options. The encodings map to dedicated engine kernels (str_hex_decode / str_base64_decode), so unknown names cannot be dispatched.

Solutions

1. Use encoding='hex' or encoding='base64'.
2. Fix casing to lowercase: 'base64' not 'Base64'.
3. For utf-8 decoding of bytes, that is a String dtype concern, not str.decode — handle it outside the expression.

Example fix

// before
pl.col('s').str.decode('utf-8')
// after
pl.col('s').str.decode('base64')

if encoding not in ('hex', 'base64'):
    raise ValueError(f'encoding must be hex or base64, got {encoding!r}')

from typing import Literal
def is_transfer_encoding(e: str) -> bool:
    return e in ('hex', 'base64')

try:
    expr = pl.col('s').str.decode(enc)
except ValueError:
    expr = pl.col('s').str.decode('base64')

When it happens

Trigger: Calling Expr.str.decode('utf-8') or decode(encoding='base32') or with case variants like 'Base64' / None.

Common situations: Confusing text encoding (utf-8) with transfer encoding (hex/base64); casing mistakes when the encoding comes from config; assuming other encodings like base32 are supported.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• `encoding` must be one of
• arr.dot query vector must be one-dimensional
• can not match overlapping patterns when leftmost == True
• cannot specify both `n` and `fraction`
• `columns` arg should only have unique values, got

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/3c1134d655637aad. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/expr/string.py:1433

        >>> df.with_columns(pl.col("color").str.decode("hex").alias("decoded"))
        shape: (3, 2)
        ┌────────┬─────────────────┐
        │ color  ┆ decoded         │
        │ ---    ┆ ---             │
        │ str    ┆ binary          │
        ╞════════╪═════════════════╡
        │ 000000 ┆ b"\x00\x00\x00" │
        │ ffff00 ┆ b"\xff\xff\x00" │
        │ 0000ff ┆ b"\x00\x00\xff" │
        └────────┴─────────────────┘
        """
        if encoding == "hex":
            return wrap_expr(self._pyexpr.str_hex_decode(strict))
        elif encoding == "base64":
            return wrap_expr(self._pyexpr.str_base64_decode(strict))
        else:
            msg = f"`encoding` must be one of {{'hex', 'base64'}}, got {encoding!r}"
            raise ValueError(msg)

    def encode(self, encoding: TransferEncoding) -> Expr:
        """
        Encode values using the provided encoding.

        Parameters
        ----------
        encoding : {'hex', 'base64'}
            The encoding to use.

        .. engine-support:: in-memory, streaming, distributed

        Returns
        -------
        Expr
            Expression of data type :class:`String`.

        Examples

View on GitHub (pinned to fe841f959e)