{"record":{"id":"02c15c4be60927b7","repo":"pola-rs/polars","slug":"schema-cannot-be-used-with-use-pyarrow-true","errorCode":null,"errorMessage":"`schema` cannot be used with `use_pyarrow=True`","messagePattern":"`schema` cannot be used with `use_pyarrow=True`","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/parquet/functions.py","lineNumber":238,"sourceCode":"    if schema is not None:\n        msg = \"the `schema` parameter of `read_parquet` is considered unstable.\"\n        issue_unstable_warning(msg)\n\n    if hive_schema is not None:\n        msg = \"the `hive_schema` parameter of `read_parquet` is considered unstable.\"\n        issue_unstable_warning(msg)\n\n    # Dispatch to pyarrow if requested\n    if use_pyarrow:\n        if n_rows is not None:\n            msg = \"`n_rows` cannot be used with `use_pyarrow=True`\"\n            raise ValueError(msg)\n        if include_file_paths is not None:\n            msg = \"`include_file_paths` cannot be used with `use_pyarrow=True`\"\n            raise ValueError(msg)\n        if schema is not None:\n            msg = \"`schema` cannot be used with `use_pyarrow=True`\"\n            raise ValueError(msg)\n        if hive_schema is not None:\n            msg = (\n                \"cannot use `hive_partitions` with `use_pyarrow=True`\"\n                \"\\n\\nHint: Pass `pyarrow_options` instead with a 'partitioning' entry.\"\n            )\n            raise TypeError(msg)\n        return _read_parquet_with_pyarrow(\n            source,\n            columns=columns,\n            storage_options=storage_options,\n            pyarrow_options=pyarrow_options,\n            memory_map=memory_map,\n            rechunk=rechunk,\n        )\n\n    if allow_missing_columns is not None:\n        issue_deprecation_warning(\n            \"the parameter `allow_missing_columns` for `read_parquet` is deprecated. \"","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/parquet/functions.py#L220-L256","documentation":"ValueError raised by pl.read_parquet when use_pyarrow=True is combined with schema. Passing an explicit schema (overriding the one stored in the parquet file) is a native-reader feature; the pyarrow dispatch path takes no schema argument, so the mismatch is rejected up front. Note that even on the native path schema is flagged as unstable.","triggerScenarios":"pl.read_parquet('f.parquet', use_pyarrow=True, schema={'a': pl.Int64, ...}) — any non-None schema with use_pyarrow=True.","commonSituations":"Forcing a corrected schema onto files whose stored schema is wrong (e.g. decimals or dates mis-typed by an upstream writer) while also enabling use_pyarrow for type compatibility — the two goals collide.","solutions":["Remove use_pyarrow and pass schema to the native engine (schema={'a': pl.Int64, ...}).","Keep use_pyarrow=True and cast after reading: pl.read_parquet(...).cast(schema) or selective .with_columns casts.","With pyarrow, read via pyarrow.parquet.read_table with a schema passed to its reader options, then convert with pl.from_arrow."],"exampleFix":"# before\npl.read_parquet('f.parquet', use_pyarrow=True, schema=schema)\n\n# after\npl.read_parquet('f.parquet', schema=schema)  # native engine\n# or\npl.read_parquet('f.parquet', use_pyarrow=True).cast(schema)","handlingStrategy":"validation","validationCode":"if schema is not None and use_pyarrow:\n    use_pyarrow = False  # or plan a post-read .cast(schema)\npl.read_parquet(path, schema=schema, use_pyarrow=use_pyarrow)","typeGuard":null,"tryCatchPattern":"try:\n    df = pl.read_parquet(path, use_pyarrow=True, schema=schema)\nexcept ValueError as e:\n    if '`schema` cannot be used' in str(e):\n        df = pl.read_parquet(path, use_pyarrow=True).cast(schema)\n    else:\n        raise","preventionTips":["Remember schema on read_parquet is native-only and unstable — prefer post-read casts.","Store schema-override logic in one place so engine switches cannot silently break it.","Prefer .cast(schema) or with_columns casts when the pyarrow engine is mandatory."],"tags":["parquet","pyarrow","parameter-conflict","schema","io"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}