{"record":{"id":"51b3043256bc1c9d","repo":"pola-rs/polars","slug":"format-must-be-one-of-binary-json-got-f-51b304","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/expr/expr.py","lineNumber":589,"sourceCode":"        >>> expr = pl.col(\"foo\").sum().over(\"bar\")\n        >>> bytes = expr.meta.serialize()\n        >>> pl.Expr.deserialize(io.BytesIO(bytes))\n        <Expr ['col(\"foo\").sum().over([col(\"ba…'] at ...>\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 = BytesIO(source)\n\n        if format == \"binary\":\n            deserializer = PyExpr.deserialize_binary\n        elif format == \"json\":\n            deserializer = PyExpr.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_pyexpr(deserializer(source))\n\n    def to_physical(self) -> Expr:\n        \"\"\"\n        Cast to physical representation of the logical dtype.\n\n        - :func:`polars.datatypes.Date` -> :func:`polars.datatypes.Int32`\n        - :func:`polars.datatypes.Datetime` -> :func:`polars.datatypes.Int64`\n        - :func:`polars.datatypes.Time` -> :func:`polars.datatypes.Int64`\n        - :func:`polars.datatypes.Duration` -> :func:`polars.datatypes.Int64`\n        - :func:`polars.datatypes.Categorical` -> :func:`polars.datatypes.UInt32`\n        - `List(inner)` -> `List(physical of inner)`\n        - `Array(inner)` -> `Struct(physical of inner)`\n        - `Struct(fields)` -> `Array(physical of fields)`\n\n        Other data types will be left unchanged.\n","sourceCodeStart":571,"sourceCodeEnd":607,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/expr/expr.py#L571-L607","documentation":"Expr.deserialize supports exactly two formats: 'binary' (polars' compact self-describing format) and 'json'. Any other format string — 'pickle', 'arrow', or None where a string is expected — raises ValueError after the source is normalised but before a deserializer is chosen. Serialize and deserialize must use matching formats.","triggerScenarios":"pl.Expr.deserialize(source, format='pickle'); format=None on a code path that forwards it verbatim; typos like 'jsn' or 'JSON'.","commonSituations":"Caching serialised expressions inside pickle-based pipelines; interop code assuming pickle because other libraries default to it; format strings threaded through from config without validation.","solutions":["Use 'binary' (compact default) or 'json' (debuggable) exactly","Pair formats on both sides: expr.serialize(format='json') with pl.Expr.deserialize(src, format='json')","If pickle is needed, pickle the produced bytes instead: pickle.dumps(expr.serialize())"],"exampleFix":"# before\nexpr = pl.Expr.deserialize(data, format='pickle')  # ValueError\n\n# after\nexpr = pl.Expr.deserialize(data, format='binary')\n# round-trip: blob = expr.serialize(format='json'); expr = pl.Expr.deserialize(blob, format='json')","handlingStrategy":"validation","validationCode":"VALID_FORMATS = ('binary', 'json')\n\nif fmt not in VALID_FORMATS:\n    raise ValueError(f\"format must be one of {VALID_FORMATS}\")\nexpr = pl.Expr.deserialize(source, format=fmt)","typeGuard":"from typing import Literal, TypeGuard\n\nDeserializeFormat = Literal['binary', 'json']\n\ndef is_deserialize_format(v: str) -> TypeGuard[DeserializeFormat]:\n    return v in ('binary', 'json')","tryCatchPattern":null,"preventionTips":["Type the parameter Literal['binary','json']","Always pair serialize/deserialize format arguments explicitly","For pickle pipelines, pickle the bytes from expr.serialize() instead of asking deserialize for 'pickle'"],"tags":["serialization","expr","format-validation","deserialize"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}