pola-rs/polars · error · ComputeError

iceberg reader_override='native' failed

Error message

iceberg reader_override='native' failed: {fallback_reason}

What it means

The fast 'native' (Rust) reader path could not handle this Iceberg table, and reader_override='native' explicitly forbade the automatic fallback to the Python pyiceberg reader. polars raises ComputeError carrying the original fallback_reason, replacing what would have been a silent fallback.

Solutions

1. Remove reader_override='native' (pass None) to allow automatic fallback to pyiceberg.
2. Set reader_override='pyiceberg' explicitly to force the Python reader.
3. Check the fallback_reason in the message to see which table feature the native reader lacks; simplify the table (e.g. remove unsupported deletes/transforms) if native reading is required.

Example fix

// before
df = pl.scan_iceberg(uri, reader_override="native").collect()  # fails on unsupported feature

// after
df = pl.scan_iceberg(uri).collect()  # auto-fallback to pyiceberg when needed

if requires_pyiceberg_features(table):
    reader_override = "pyiceberg"  # or None to allow auto-fallback

def native_reader_is_safe(reader_override: str | None) -> bool:
    return reader_override in (None, "pyiceberg")

try:
    df = pl.scan_iceberg(uri, reader_override="native").collect()
except pl.exceptions.ComputeError as e:
    if "reader_override='native' failed" in str(e):
        df = pl.scan_iceberg(uri, reader_override="pyiceberg").collect()
    else:
        raise

When it happens

Trigger: Scanning a table whose features are unsupported by the native reader (e.g. certain partition transforms, deletes/equality deletes, unsupported formats) while forcing reader_override='native' so the pyiceberg fallback branch is rejected.

Common situations: Developers pin reader_override='native' for performance and then hit a table using advanced Iceberg features; version drift where a new table feature is not yet native-supported.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• cannot combine `snapshot_id` with…
• Cannot infer partition value from Parquet metadata for…
• cannot sink to static Iceberg table
• cannot use NoopCatalog with
• failed to load catalog for

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/c0684cb74f66a4af. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/io/iceberg/_dataset.py:589

                position_delete_files=position_delete_files,
                deletion_vectors=deletion_vectors,
                min_max_statistics=min_max_statistics,
                statistics_loader=statistics_loader,
                storage_options=storage_options,
                row_count=(
                    (total_physical_rows, total_deleted_rows)
                    if (
                        self.use_metadata_statistics
                        and (self.fast_deletion_count or total_deleted_rows == 0)
                    )
                    else None
                ),
                snapshot_id_key=snapshot_id_key,
            )

        elif reader_override == "native":
            msg = f"iceberg reader_override='native' failed: {fallback_reason}"
            raise ComputeError(msg)

        if verbose:
            eprint(
                "IcebergScanResolver: to_dataset_scan(): "
                f"fallback to python[pyiceberg] scan: {fallback_reason}"
            )

        import polars.io.iceberg._utils

        func = partial(
            polars.io.iceberg._utils._scan_pyarrow_dataset_impl,
            tbl,
            snapshot_id=snapshot_id,
            from_snapshot_id_exclusive=self.from_snapshot_id_exclusive,
            to_snapshot_id_inclusive=self.to_snapshot_id_inclusive,
            n_rows=limit,
            with_columns=projection,
            iceberg_table_filter=iceberg_table_filter,

View on GitHub (pinned to fe841f959e)