pola-rs/polars · error · ValueError

iceberg: unknown value for reader_override

Error message

iceberg: unknown value for reader_override: '{reader_override}', expected one of ('native', 'pyiceberg')

What it means

The reader_override option for Iceberg scans only accepts 'native' or 'pyiceberg'; any other string fails this validation in _to_dataset_scan_impl. polars raises ValueError naming the accepted values.

Solutions

1. Set reader_override='native' or reader_override='pyiceberg'.
2. Pass None/omit the argument to use the default reader-selection logic.
3. If the value comes from config, normalize it (strip/lower) and validate against the allowed set before the call.

Example fix

// before
pl.scan_iceberg(uri, reader_override="polars")  # invalid

// after
pl.scan_iceberg(uri, reader_override="pyiceberg")

ALLOWED = {"native", "pyiceberg"}
reader_override = reader_override if reader_override in ALLOWED else None

def is_valid_reader_override(v: object) -> bool:
    return v in ("native", "pyiceberg")

try:
    df = pl.scan_iceberg(uri, reader_override=ro).collect()
except ValueError as e:
    if "reader_override" in str(e):
        df = pl.scan_iceberg(uri).collect()
    else:
        raise

When it happens

Trigger: Calling scan_iceberg/to_dataset_scan with reader_override set to any string other than 'native' or 'pyiceberg' (e.g. 'polars', 'arrow', None-as-string '', or a misspelling like 'pyiceberg ' with whitespace).

Common situations: Copy-pasted configuration from other engines, typos, or config files where reader_override is populated dynamically from user input.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• cannot sink to static Iceberg table
• cannot use credential_provider when passing a DeltaTable…
• cannot use NoopCatalog with
• failed to load catalog for
• `format` must be one of

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

Appendix: source

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

            if verbose:
                eprint(
                    "IcebergScanResolver: to_dataset_scan(): early return "
                    f"({snapshot_id_key = })"
                )

            return None

        # Take from parameter first then envvar
        reader_override = self.reader_override or os.getenv(
            "POLARS_ICEBERG_READER_OVERRIDE"
        )

        if reader_override and reader_override not in ["native", "pyiceberg"]:
            msg = (
                "iceberg: unknown value for reader_override: "
                f"'{reader_override}', expected one of ('native', 'pyiceberg')"
            )
            raise ValueError(msg)

        fallback_reason = (
            "forced reader_override='pyiceberg'"
            if reader_override == "pyiceberg"
            else None
        )

        selected_fields = ("*",) if projection is None else tuple(projection)

        projected_iceberg_schema = (
            iceberg_schema
            if selected_fields == ("*",)
            else iceberg_schema.select(*selected_fields)
        )

        initial_defaults = {
            x: value
            for x in projected_iceberg_schema.field_ids

View on GitHub (pinned to fe841f959e)