{"record":{"id":"bbe3e624715a28af","repo":"pola-rs/polars","slug":"format-must-be-one-of-binary-json-got-f","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/dataframe/frame.py","lineNumber":559,"sourceCode":"        │ 1   ┆ 4.0 │\n        │ 2   ┆ 5.0 │\n        │ 3   ┆ 6.0 │\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 = PyDataFrame.deserialize_binary\n        elif format == \"json\":\n            deserializer = PyDataFrame.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_pydf(deserializer(source))\n\n    @classmethod\n    def _from_pydf(cls, py_df: PyDataFrame) -> DataFrame:\n        \"\"\"Construct Polars DataFrame from FFI PyDataFrame object.\"\"\"\n        df = cls.__new__(cls)\n        df._df = py_df\n        return df\n\n    @classmethod\n    def _from_arrow(\n        cls,\n        data: pa.Table | pa.RecordBatch,\n        schema: SchemaDefinition | None = None,\n        *,\n        schema_overrides: SchemaDict | None = None,\n        rechunk: bool = True,","sourceCodeStart":541,"sourceCodeEnd":577,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L541-L577","documentation":"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.","triggerScenarios":"pl.DataFrame.deserialize(path, format='ipc') or 'csv' or 'parquet' or Format.BINARY enum from another lib; passing format=None; case variants like 'JSON'.","commonSituations":"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'.","solutions":["Use format='binary' for data written with serialize() default, and format='json' for serialize(format='json')","For IPC files, prefer pl.read_ipc(source); for JSON use pl.read_json","Verify the writer side and mirror its format token exactly"],"exampleFix":"# before\npl.DataFrame.deserialize('df.ipc', format='ipc')\n\n# after\npl.read_ipc('df.ipc')\n# or, for serialize() output:\npl.DataFrame.deserialize('df.bin', format='binary')","handlingStrategy":"validation","validationCode":"VALID = {'binary', 'json'}\nif format not in VALID:\n    raise ValueError(f'format must be one of {VALID}, got {format!r}')\ndf = pl.DataFrame.deserialize(src, format=format)","typeGuard":"def is_deserialize_format(fmt: object) -> bool:\n    return isinstance(fmt, str) and fmt in {'binary', 'json'}","tryCatchPattern":null,"preventionTips":["Mirror the format token used at serialize() time","Prefer pl.read_ipc / pl.read_json for reading files","Centralize format constants in one place instead of string literals at call sites"],"tags":["deserialization","format","dataframe"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}