What causes "`schema` cannot be used with `use_pyarrow=True`" in pola-rs/polars?

Remove use_pyarrow and pass schema to the native engine (schema={'a': pl.Int64, ...}).

pola-rs/polars · error · ValueError

`schema` cannot be used with `use_pyarrow=True`

Error message

`schema` cannot be used with `use_pyarrow=True`

What it means

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.

Source

Thrown at py-polars/src/polars/io/parquet/functions.py:238

    if schema is not None:
        msg = "the `schema` parameter of `read_parquet` is considered unstable."
        issue_unstable_warning(msg)

    if hive_schema is not None:
        msg = "the `hive_schema` parameter of `read_parquet` is considered unstable."
        issue_unstable_warning(msg)

    # Dispatch to pyarrow if requested
    if use_pyarrow:
        if n_rows is not None:
            msg = "`n_rows` cannot be used with `use_pyarrow=True`"
            raise ValueError(msg)
        if include_file_paths is not None:
            msg = "`include_file_paths` cannot be used with `use_pyarrow=True`"
            raise ValueError(msg)
        if schema is not None:
            msg = "`schema` cannot be used with `use_pyarrow=True`"
            raise ValueError(msg)
        if hive_schema is not None:
            msg = (
                "cannot use `hive_partitions` with `use_pyarrow=True`"
                "\n\nHint: Pass `pyarrow_options` instead with a 'partitioning' entry."
            )
            raise TypeError(msg)
        return _read_parquet_with_pyarrow(
            source,
            columns=columns,
            storage_options=storage_options,
            pyarrow_options=pyarrow_options,
            memory_map=memory_map,
            rechunk=rechunk,
        )

    if allow_missing_columns is not None:
        issue_deprecation_warning(
            "the parameter `allow_missing_columns` for `read_parquet` is deprecated. "

View on GitHub (pinned to df599052da)

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.

Example fix

# before
pl.read_parquet('f.parquet', use_pyarrow=True, schema=schema)

# after
pl.read_parquet('f.parquet', schema=schema)  # native engine
# or
pl.read_parquet('f.parquet', use_pyarrow=True).cast(schema)

Defensive patterns

Strategy: validation

Validate before calling

if schema is not None and use_pyarrow:
    use_pyarrow = False  # or plan a post-read .cast(schema)
pl.read_parquet(path, schema=schema, use_pyarrow=use_pyarrow)

Try / catch

try:
    df = pl.read_parquet(path, use_pyarrow=True, schema=schema)
except ValueError as e:
    if '`schema` cannot be used' in str(e):
        df = pl.read_parquet(path, use_pyarrow=True).cast(schema)
    else:
        raise

Prevention

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.

When it happens

Trigger: pl.read_parquet('f.parquet', use_pyarrow=True, schema={'a': pl.Int64, ...}) — any non-None schema with use_pyarrow=True.

Common situations: 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.

Related errors

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/02c15c4be60927b7. Report an issue: GitHub.