pola-rs/polars · error · ValueError

IcebergScanResolver: requested snapshot

Error message

IcebergScanResolver: requested snapshot {snapshot_id} did not contain a schema ID

What it means

Same class of problem as the schema() variant: the snapshot found in _to_dataset_scan_impl has schema_id = None, so the code cannot select a schema from tbl.schemas()[schema_id]. polars raises ValueError because the dataset scan requires an explicit schema.

Solutions

  1. Pin a different snapshot that records a schema_id, or pass snapshot_id=None to use tbl.schema() and current_schema_id.
  2. Upgrade/rewrite table metadata so snapshots include schema-id (e.g. via pyiceberg migrate/rewrite_table).
  3. If you control the writer, ensure it registers the current schema-id on each snapshot commit.

Example fix

// before
scan = resolver.to_dataset_scan(snapshot_id=old_snapshot_id)  # schema_id None

// after
scan = resolver.to_dataset_scan(snapshot_id=None)  # use current schema
Defensive patterns

Strategy: validation

Validate before calling

snap = tbl.snapshot_by_id(snapshot_id) if snapshot_id else tbl.current_snapshot()
if snap is not None and snap.schema_id is None:
    snapshot_id = None

Type guard

def snapshot_has_schema(tbl, snapshot_id: int | None) -> bool:
    if snapshot_id is None:
        return True
    snap = tbl.snapshot_by_id(snapshot_id)
    return snap is not None and snap.schema_id is not None

Try / catch

try:
    scan = resolver.to_dataset_scan(snapshot_id=sid)
except ValueError as e:
    if "did not contain a schema ID" in str(e):
        scan = resolver.to_dataset_scan(snapshot_id=None)
    else:
        raise

Prevention

When it happens

Trigger: Calling to_dataset_scan with a snapshot_id pointing at a snapshot lacking a schema-id field in its summary/metadata.

Common situations: Tables produced by Iceberg writers that omit the schema-id snapshot field (older writers, migrated tables), or metadata edited/tested in-place.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

            or self.to_snapshot_id_inclusive is not None
        )
        schema_id = None

        if snapshot_id is not None:
            snapshot = tbl.snapshot_by_id(snapshot_id)

            if snapshot is None:
                msg = f"iceberg snapshot ID not found: {snapshot_id}"
                raise ValueError(msg)

            schema_id = snapshot.schema_id

            if schema_id is None:
                msg = (
                    f"IcebergScanResolver: requested snapshot {snapshot_id} "
                    "did not contain a schema ID"
                )
                raise ValueError(msg)

            iceberg_schema = tbl.schemas()[schema_id]
            snapshot_id_key = f"{snapshot.snapshot_id}"
        else:
            iceberg_schema = tbl.schema()
            schema_id = tbl.metadata.current_schema_id

            current_snapshot_id = (
                v.snapshot_id if (v := tbl.current_snapshot()) is not None else None
            )
            resolved_end_snapshot_id = (
                self.to_snapshot_id_inclusive
                if self.to_snapshot_id_inclusive is not None
                else current_snapshot_id
            )
            snapshot_id_key = (
                f"incremental:{self.from_snapshot_id_exclusive}:"
                f"{resolved_end_snapshot_id}:schema:{schema_id}"

View on GitHub (pinned to fe841f959e)