{"record":{"id":"3760fc5d164c830e","repo":"pola-rs/polars","slug":"n-rows-cannot-be-used-with-use-pyarrow-true","errorCode":null,"errorMessage":"`n_rows` cannot be used with `use_pyarrow=True`","messagePattern":"`n_rows` 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":232,"sourceCode":"    Calling `read_parquet().lazy()` is an antipattern as this forces Polars to\n    materialize a full parquet file and therefore cannot push any optimizations\n    into the reader. Therefore always prefer `scan_parquet` if you want to work\n    with `LazyFrame` s.\n\n    \"\"\"\n    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,","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/parquet/functions.py#L214-L250","documentation":"pl.read_parquet raises this ValueError when use_pyarrow=True is combined with n_rows. The pyarrow dispatch path (_read_parquet_with_pyarrow) only bridges a subset of read_parquet's parameters; row limiting is implemented solely in polars' native reader, so the combination is rejected up front before any file is opened.","triggerScenarios":"pl.read_parquet('f.parquet', use_pyarrow=True, n_rows=1000). Any non-None n_rows (including 0) together with use_pyarrow=True hits the guard in read_parquet's preamble.","commonSituations":"Enabling use_pyarrow to read files with data types the native engine handled poorly (older polars versions), or to use pyarrow filesystems, while keeping an existing n_rows sampling argument; copying a pyarrow-dataset snippet into code that already limited rows.","solutions":["Drop use_pyarrow (use the default native engine) — it fully supports n_rows and is generally faster.","Keep use_pyarrow=True, remove n_rows, and slice afterwards: pl.read_parquet(...).head(1000) (note: the whole file is still decoded).","If you were using pyarrow for a specific reason, call pyarrow.parquet.read_table directly with its own row-group/fragment options instead."],"exampleFix":"# before\npl.read_parquet('f.parquet', use_pyarrow=True, n_rows=1000)\n\n# after\npl.read_parquet('f.parquet', n_rows=1000)  # native engine\n# or\npl.read_parquet('f.parquet', use_pyarrow=True).head(1000)","handlingStrategy":"validation","validationCode":"kwargs = {'use_pyarrow': True}\nif n_rows is not None:\n    kwargs.pop('use_pyarrow')  # native engine supports n_rows\npl.read_parquet(path, n_rows=n_rows, **kwargs)","typeGuard":null,"tryCatchPattern":"try:\n    df = pl.read_parquet(path, use_pyarrow=True, n_rows=n_rows)\nexcept ValueError as e:\n    if 'n_rows' in str(e) and 'use_pyarrow' in str(e):\n        df = pl.read_parquet(path, use_pyarrow=True).head(n_rows)\n    else:\n        raise","preventionTips":["Default to the native engine; only opt into use_pyarrow for a concrete reason.","Keep a checklist of native-only params (n_rows, include_file_paths, schema, hive_schema) when toggling use_pyarrow.","Wrap read_parquet in one project-level helper that encodes the compatibility rules."],"tags":["parquet","pyarrow","parameter-conflict","io"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}