{"record":{"id":"f265b5eaf80e025d","repo":"pola-rs/polars","slug":"write-parquet-with-use-pyarrow-true-cannot-be-co","errorCode":null,"errorMessage":"write_parquet with `use_pyarrow=True` cannot be combined with `metadata`","messagePattern":"write_parquet with `use_pyarrow=True` cannot be combined with `metadata`","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/dataframe/frame.py","lineNumber":4312,"sourceCode":"        ... )\n        \"\"\"\n        if compression is None:\n            compression = \"uncompressed\"\n        if isinstance(file, (str, Path)):\n            if partition_by is not None or (\n                pyarrow_options is not None and pyarrow_options.get(\"partition_cols\")\n            ):\n                file = normalize_filepath(file, check_not_directory=False)\n            else:\n                file = normalize_filepath(file)\n\n        if use_pyarrow:\n            if statistics == \"full\" or isinstance(statistics, dict):\n                msg = \"write_parquet with `use_pyarrow=True` allows only boolean values for `statistics`\"\n                raise ValueError(msg)\n            if metadata is not None:\n                msg = \"write_parquet with `use_pyarrow=True` cannot be combined with `metadata`\"\n                raise ValueError(msg)\n            if mkdir:\n                msg = \"write_parquet with `use_pyarrow=True` cannot be combined with `mkdir`\"\n                raise ValueError(msg)\n\n            tbl = self.to_arrow()\n            data = {}\n\n            for i, column in enumerate(tbl):\n                # extract the name before casting\n                name = f\"column_{i}\" if column._name is None else column._name\n\n                data[name] = column\n\n            tbl = pa.table(data)\n\n            # do not remove this import!\n            # needed below\n            import pyarrow.parquet  # noqa: F401","sourceCodeStart":4294,"sourceCodeEnd":4330,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/dataframe/frame.py#L4294-L4330","documentation":"Raised by DataFrame.write_parquet(use_pyarrow=True) when a `metadata` mapping is also supplied. Custom key-value file metadata is implemented by polars' native rust writer; the pyarrow delegation path has no plumbing for it, so the combination is rejected up front (before file creation) instead of silently dropping your metadata.","triggerScenarios":"`df.write_parquet('f.parquet', use_pyarrow=True, metadata={'creator': 'etl-7'})`. Typically appears when use_pyarrow is enabled for pyarrow_options/partition_by while a shared write helper always attaches metadata.","commonSituations":"ETL lineage pipelines stamping dataset metadata on every file; writers parameterized so that partitioned outputs force use_pyarrow while metadata stays on; refactors that moved a metadata dict into a generic kwargs passthrough.","solutions":["Drop `use_pyarrow=True` so the native writer applies your metadata","Or keep use_pyarrow=True and stamp metadata afterwards with pyarrow: read the parquet file's metadata, rewrite via `pq.write_table(..., additional_metadata=...)` — or simply omit it","Restructure the shared writer so metadata is only passed on native-writer calls"],"exampleFix":"# before\ndf.write_parquet('f.parquet', use_pyarrow=True, metadata={'creator': 'etl'})\n\n# after\ndf.write_parquet('f.parquet', metadata={'creator': 'etl'})  # native writer","handlingStrategy":"validation","validationCode":"if use_pyarrow and metadata is not None:\n    raise ValueError('metadata requires the native writer; drop use_pyarrow')\ndf.write_parquet(path, use_pyarrow=use_pyarrow, metadata=metadata)","typeGuard":null,"tryCatchPattern":"try:\n    df.write_parquet(path, use_pyarrow=True, metadata=metadata)\nexcept ValueError as e:\n    if 'cannot be combined with `metadata`' in str(e):\n        df.write_parquet(path, metadata=metadata)  # native writer honors it\n    else:\n        raise","preventionTips":["Attach file metadata only through the native writer path","Split writer configs: pyarrow path (partition_by, pyarrow_options) vs native path (metadata, rich statistics)","Add a pre-flight check that rejects incompatible write_parquet kwarg combinations"],"tags":["parquet","write","argument-mismatch","metadata"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}