pola-rs/polars · error · ValueError

`format` must be one of

Error message

`format` must be one of {{'binary', 'json'}}, got {format!r}

What it means

ValueError raised by Expr.meta.serialize when the format argument is neither 'binary' nor 'json'. Only those two serialization formats are implemented for expression trees, and anything else (including common mistakes like 'yaml', 'jsonl', or 'text') is rejected with the received value echoed back.

Solutions

1. Use format='binary' (compact) or format='json' (readable)
2. Default the parameter in wrappers to one of the two valid values
3. Validate with a whitelist before calling serialize in generic pipelines

Example fix

# before
expr.meta.serialize(format='yaml')
# after
expr.meta.serialize(format='json')

assert format in ('binary', 'json'), f'bad format {format!r}'

def is_valid_format(fmt: object) -> bool:
    return fmt in ('binary', 'json')

try:
    expr.meta.serialize(format=fmt)
except ValueError:
    fmt = 'json'
    expr.meta.serialize(format=fmt)

When it happens

Trigger: pl.col('a').sum().meta.serialize(format='yaml'), or passing file paths/None into the format parameter, or a variable that silently evaluated to an unexpected string.

Common situations: Generic serialize/deserialize wrapper functions defaulting format to something else; confusion with DataFrame.write_json or serde formats used elsewhere in polars.

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

• `arctan2` expected a `str` or `Expr` got a
• `arctan2` expected a `str` or `Expr` got a
• cannot use credential_provider when passing a DeltaTable…
• `how` must be one of
• invalid input for `aggregate_function` argument

AI-assisted analysis of pola-rs/polars@fc24390824 (2026-08-28). Data as JSON: /api/errors/67af37abcd0b4aa2. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/expr/meta.py:449

        >>> expr = pl.col("foo").sum().over("bar")
        >>> bytes = expr.meta.serialize()
        >>> type(bytes)
        <class 'bytes'>

        The bytes can later be deserialized back into an `Expr` object.

        >>> import io
        >>> pl.Expr.deserialize(io.BytesIO(bytes))
        <Expr ['col("foo").sum().over([col("ba…'] at ...>
        """
        if format == "binary":
            serializer = self._pyexpr.serialize_binary
        elif format == "json":
            serializer = self._pyexpr.serialize_json
        else:
            msg = f"`format` must be one of {{'binary', 'json'}}, got {format!r}"
            raise ValueError(msg)

        return serialize_polars_object(serializer, file, format)

    @overload
    def tree_format(
        self,
        *,
        return_as_string: Literal[False] = ...,
        schema: None | SchemaDict = None,
    ) -> None: ...

    @overload
    def tree_format(
        self, *, return_as_string: Literal[True], schema: None | SchemaDict = None
    ) -> str: ...

    def tree_format(
        self, *, return_as_string: bool = False, schema: None | SchemaDict = None

View on GitHub (pinned to fc24390824)