pola-rs/polars · error · ValueError

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

Error message

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

What it means

Expr.meta.serialize accepts exactly two formats — 'binary' (default, MessagePack-based) and 'json' — and dispatches to the matching Rust serializer before writing via serialize_polars_object. Any other format string (typos like 'jsonl', 'pickle', 'yaml') hits the else branch and raises ValueError. The output is an expression tree dump used to persist or inspect logical plans.

Source

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

        >>> 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 write_json(self, file: None = ...) -> str: ...

    @overload
    def write_json(self, file: IOBase | str | Path) -> None: ...

    @deprecated("`meta.write_json` was renamed; use `meta.serialize` instead")
    def write_json(self, file: IOBase | str | Path | None = None) -> str | None:
        """
        Write expression to json.

        .. deprecated:: 0.20.11
            This method has been renamed to :meth:`serialize`.
        """
        return self.serialize(file, format="json")

View on GitHub (pinned to df599052da)

Solutions

1. Use format='binary' (compact) or format='json' (readable) — or omit format for binary.
2. If you need JSON text into a string, meta.serialize() with format='json' and no file returns it.
3. Validate the config value against {'binary', 'json'} before it reaches polars.

Example fix

# before
expr.meta.serialize(buf, format='msgpack')

# after
expr.meta.serialize(buf, format='binary')
# or
json_str = expr.meta.serialize(format='json')

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

def is_serialize_format(f: str) -> bool:
    return f in ('binary', 'json')

When it happens

Trigger: expr.meta.serialize(file, format='msgpack'), format='text', or a format variable that defaulted to None.

Common situations: Guessing format names from other polars APIs (scan_parquet-style strings); config-driven serialization where the format key is optional and resolves to None; version drift: write_json was renamed to meta.serialize, so call sites were hand-migrated and the format value mistyped.

Related errors

• cannot specify both `value` and `strategy`
• must specify either a fill `value` or `strategy`
• strategy {strategy!r} is not supported
• reinterpret requires exactly one of `signed` or `dtype` to b
• cannot specify both `n` and `fraction`

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