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

DataFrame.deserialize only supports the two serialization formats polars emits, 'binary' (Arrow IPC) and 'json'; anything else fails the if/elif chain and raises ValueError listing the allowed values. The format string selects the Rust-side deserializer (PyDataFrame.deserialize_binary / deserialize_json), so an unknown token cannot be forwarded.

Source

Thrown at py-polars/src/polars/dataframe/frame.py:559

        │ 1   ┆ 4.0 │
        │ 2   ┆ 5.0 │
        │ 3   ┆ 6.0 │
        └─────┴─────┘
        """
        if isinstance(source, StringIO):
            source = BytesIO(source.getvalue().encode())
        elif isinstance(source, (str, Path)):
            source = normalize_filepath(source)
        elif isinstance(source, bytes):
            source = io.BytesIO(source)

        if format == "binary":
            deserializer = PyDataFrame.deserialize_binary
        elif format == "json":
            deserializer = PyDataFrame.deserialize_json
        else:
            msg = f"`format` must be one of {{'binary', 'json'}}, got {format!r}"
            raise ValueError(msg)

        return cls._from_pydf(deserializer(source))

    @classmethod
    def _from_pydf(cls, py_df: PyDataFrame) -> DataFrame:
        """Construct Polars DataFrame from FFI PyDataFrame object."""
        df = cls.__new__(cls)
        df._df = py_df
        return df

    @classmethod
    def _from_arrow(
        cls,
        data: pa.Table | pa.RecordBatch,
        schema: SchemaDefinition | None = None,
        *,
        schema_overrides: SchemaDict | None = None,
        rechunk: bool = True,

View on GitHub (pinned to df599052da)

Solutions

1. Use format='binary' for data written with serialize() default, and format='json' for serialize(format='json')
2. For IPC files, prefer pl.read_ipc(source); for JSON use pl.read_json
3. Verify the writer side and mirror its format token exactly

Example fix

# before
pl.DataFrame.deserialize('df.ipc', format='ipc')

# after
pl.read_ipc('df.ipc')
# or, for serialize() output:
pl.DataFrame.deserialize('df.bin', format='binary')

VALID = {'binary', 'json'}
if format not in VALID:
    raise ValueError(f'format must be one of {VALID}, got {format!r}')
df = pl.DataFrame.deserialize(src, format=format)

def is_deserialize_format(fmt: object) -> bool:
    return isinstance(fmt, str) and fmt in {'binary', 'json'}

When it happens

Trigger: pl.DataFrame.deserialize(path, format='ipc') or 'csv' or 'parquet' or Format.BINARY enum from another lib; passing format=None; case variants like 'JSON'.

Common situations: Assuming deserialize mirrors read_* naming (write_ipc -> format='ipc'); copy-pasting format names from other APIs; round-trip code where the writer used write_json but reader says 'ipc'.

Related errors

• dimensions of columns arg must match data dimensions
• cannot create DataFrame from zero-dimensional array
• cannot create DataFrame from array with more than two dimens
• dimensions of `schema` ({n_schema_cols}) must match data dim
• cannot initialize Series from DataFrame without any columns

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