pola-rs/polars · error · ComputeError

failed to load catalog for

Error message

failed to load catalog for {fn_name}() ({error = }). Configure the default PyIceberg catalog, or pass a catalog via the 'catalog' parameter, or pass a PyIceberg table object instead of the name.{static_metadata_hint}

What it means

When no catalog parameter is supplied, polars calls pyiceberg.catalog.load_catalog() to resolve the default catalog; if that fails (bad/missing pyiceberg config, network/auth errors), it wraps the error in a ComputeError telling the user how to configure or pass a catalog.

Solutions

Configure the default pyiceberg catalog (e.g. via PYICEBERG_CATALOG env var or ~/.pyiceberg.yaml) and retry
Pass an explicit catalog: pyiceberg.catalog.load_catalog(name, **props) via the catalog parameter
Pass a pyiceberg Table object directly instead of a table name to skip catalog loading

Example fix

// before
pl.scan_iceberg('db.tbl')  # no catalog configured
// after
import pyiceberg.catalog
cat = pyiceberg.catalog.load_catalog('default', uri='https://rest-catalog/...')
pl.scan_iceberg('db.tbl', catalog=cat)

Defensive patterns

Strategy: try-catch

Validate before calling

import pyiceberg.catalog
try:
    cat = pyiceberg.catalog.load_catalog()
except Exception as e:
    raise RuntimeError('Configure default pyiceberg catalog or pass catalog=...') from e

Try / catch

try:
    lf = pl.scan_iceberg('db.tbl')
except pl.exceptions.ComputeError as e:
    if 'failed to load catalog' in str(e):
        cat = pyiceberg.catalog.load_catalog('default', **props)
        lf = pl.scan_iceberg('db.tbl', catalog=cat)

Prevention

Set up ~/.pyiceberg.yaml or PYICEBERG_CATALOG before calling scan_iceberg/read_iceberg
Pass an explicitly loaded Catalog via the catalog parameter in production code
Verify catalog connectivity/credentials in a preflight check

When it happens

Trigger: Calling pl.scan_iceberg/read_iceberg with catalog=None while the default pyiceberg catalog is unconfigured (no ~/.pyiceberg.yaml / env vars) or fails to initialize (bad credentials, unreachable catalog endpoint).

Common situations: Missing pyiceberg.yaml, wrong PYICEBERG_CATALOG env var, expired cloud credentials, or unreachable REST/Hive/Glue catalog endpoint.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

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

Appendix: source

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

            except Exception as error:
                static_metadata_hint = (
                    (
                        " "
                        "If you intended to pass a static metadata path, "
                        "ensure it is an absolute path."
                    )
                    if fn_name == "scan_iceberg"
                    else ""
                )

                msg = (
                    f"failed to load catalog for {fn_name}() ({error = }). "
                    "Configure the default PyIceberg catalog, or pass "
                    "a catalog via the 'catalog' parameter, or pass a PyIceberg "
                    "table object instead of the name."
                    f"{static_metadata_hint}"
                )
                raise ComputeError(msg) from error

            catalog_config = IcebergCatalogConfig.from_catalog(default_catalog)

        if catalog_config.class_ == NoopCatalog:
            msg = f"cannot use NoopCatalog with {fn_name}()"
            raise TypeError(msg)

        return catalog_config


@dataclass(kw_only=True)
class IcebergScanResolver:
    """
    Iceberg scan resolver.

    Defers scan resolution to run during IR resolution.
    """

View on GitHub (pinned to fe841f959e)