{"record":{"id":"e012795cd4cc2ed8","repo":"pola-rs/polars","slug":"format-must-be-one-of-binary-json-got-f-e01279","errorCode":null,"errorMessage":"`format` must be one of {'binary', 'json'}, got {format!r}","messagePattern":"`format` must be one of (.+?), got (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/frame.py","lineNumber":495,"sourceCode":"        │ i64 │\n        ╞═════╡\n        │ 6   │\n        └─────┘\n        \"\"\"\n        if isinstance(source, StringIO):\n            source = BytesIO(source.getvalue().encode())\n        elif isinstance(source, (str, Path)):\n            source = normalize_filepath(source)\n        elif isinstance(source, bytes):\n            source = io.BytesIO(source)\n\n        if format == \"binary\":\n            deserializer = PyLazyFrame.deserialize_binary\n        elif format == \"json\":\n            deserializer = PyLazyFrame.deserialize_json\n        else:\n            msg = f\"`format` must be one of {{'binary', 'json'}}, got {format!r}\"\n            raise ValueError(msg)\n\n        return cls._from_pyldf(deserializer(source))\n\n    @property\n    def columns(self) -> list[str]:\n        \"\"\"\n        Get the column names.\n\n        Returns\n        -------\n        list of str\n            A list containing the name of each column in order.\n\n        Warnings\n        --------\n        Determining the column names of a LazyFrame requires resolving its schema,\n        which is a potentially expensive operation.\n        Using :meth:`collect_schema` is the idiomatic way of resolving the schema.","sourceCodeStart":477,"sourceCodeEnd":513,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/lazyframe/frame.py#L477-L513","documentation":"`LazyFrame.deserialize` (frame.py:495) reconstructs a `LazyFrame` from serialized plan bytes and dispatches on the `format` argument: `'binary'` maps to `PyLazyFrame.deserialize_binary` and `'json'` to `deserialize_json`. Any other value (pickle, serde, uppercase variants, typos) raises ValueError after the source has been normalized to a file path or `BytesIO` but before deserialization runs.","triggerScenarios":"`pl.LazyFrame.deserialize(data, format='pickle')`, `format='JSON'`, `format='json '` (whitespace), or any string not exactly `'binary'` or `'json'`. `data` itself may be `str`/`Path`/`bytes`/binary IO; only `format` is validated here.","commonSituations":"Hand-rolled persistence of query plans with a format field stored in a database; mixing up DataFrame serialization formats (`write_ipc`/feather) with LazyFrame plan formats; config-driven format parameters passed through unvalidated.","solutions":["Use `'binary'` (default, compact) or `'json'` (exact lowercase) — and match the format used to serialize: `lf.serialize(format='json')` pairs with `deserialize(format='json')`","If the format string is dynamic, validate it against `{'binary','json'}` before calling","Store plans with `lf.serialize()` and rely on the default 'binary' to avoid mismatches"],"exampleFix":"# before\nlf2 = pl.LazyFrame.deserialize(data, format='pickle')  # ValueError\n\n# after\nlf2 = pl.LazyFrame.deserialize(data, format='binary')\n# round-trip:\npl.LazyFrame.deserialize(lf.serialize(format='json'), format='json')","handlingStrategy":"validation","validationCode":"DESERIALIZE_FORMATS = frozenset({'binary', 'json'})\n\ndef deserialize_plan(data, fmt: str = 'binary') -> pl.LazyFrame:\n    if fmt not in DESERIALIZE_FORMATS:\n        raise ValueError(f'format must be one of {sorted(DESERIALIZE_FORMATS)}, got {fmt!r}')\n    return pl.LazyFrame.deserialize(data, format=fmt)","typeGuard":"from typing import TypeGuard\n\ndef is_deserialize_format(value: object) -> TypeGuard[str]:\n    return value in ('binary', 'json')","tryCatchPattern":"try:\n    lf = pl.LazyFrame.deserialize(data, format=fmt)\nexcept ValueError as e:\n    if 'format' in str(e):\n        lf = pl.LazyFrame.deserialize(data, format='binary')\n    else:\n        raise","preventionTips":["Always serialize and deserialize with the same explicit format argument","Persist the format next to the payload (e.g. {'format': 'json', 'plan': ...})","Normalize case and strip whitespace on format strings coming from config","Prefer the default 'binary' unless human-readable plans are required"],"tags":["polars","serialization","lazyframe","validation","valueerror"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}