pola-rs/polars · error · TypeError

unknown type for `catalog` parameter

Error message

unknown type for `catalog` parameter: {type(catalog)}

What it means

The internal resolver for the `catalog` parameter of scan_iceberg/read_iceberg accepts an IcebergCatalogConfig, a pyiceberg.catalog.Catalog, or None; any other type falls through to this TypeError listing the offending type.

Solutions

1. Pass a pyiceberg.catalog.Catalog instance, e.g. pyiceberg.catalog.load_catalog('name')
2. Pass None to use the default catalog resolved from the environment/IcebergCatalogConfig
3. Wrap config in pyiceberg's catalog load (load_catalog(name, **properties)) before passing

Example fix

// before
pl.scan_iceberg('db.tbl', catalog='glue_catalog')
// after
import pyiceberg.catalog
cat = pyiceberg.catalog.load_catalog('glue_catalog')
pl.scan_iceberg('db.tbl', catalog=cat)

import pyiceberg.catalog
from pyiceberg.table import Table
def is_valid_catalog(c):
    return c is None or isinstance(c, (pyiceberg.catalog.Catalog,))

def is_catalog(obj) -> bool:
    import pyiceberg.catalog
    return isinstance(obj, pyiceberg.catalog.Catalog)

try:
    lf = pl.scan_iceberg(name, catalog=catalog)
except TypeError as e:
    if 'unknown type for `catalog`' in str(e):
        catalog = pyiceberg.catalog.load_catalog()
        lf = pl.scan_iceberg(name, catalog=catalog)

When it happens

Trigger: pl.scan_iceberg(..., catalog='my_catalog_name') or catalog=some_dict — passing a string/dict/other object instead of a Catalog or IcebergCatalogConfig.

Common situations: Passing a catalog name string (as used in other frameworks like Spark/Trino) assuming polars resolves it by name.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• `arctan2` expected a `str` or `Expr` got a
• `arctan2` expected a `str` or `Expr` got a
• cannot convert Python type
• cannot sink to static Iceberg table
• Expected Polars expression or object convertible to one, got

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

Appendix: source

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

    @staticmethod
    def _from_api_parameter_or_environment_default(
        catalog: pyiceberg.catalog.Catalog | IcebergCatalogConfig | None,
        *,
        fn_name: Literal["scan_iceberg", "sink_iceberg"],
    ) -> IcebergCatalogConfig:
        import pyiceberg.catalog
        from pyiceberg.catalog.noop import NoopCatalog

        import polars._utils.logging
        from polars._utils.logging import eprint

        if isinstance(catalog, IcebergCatalogConfig):
            catalog_config = catalog
        elif isinstance(catalog, pyiceberg.catalog.Catalog):
            catalog_config = IcebergCatalogConfig.from_catalog(catalog)
        elif catalog is not None:
            msg = f"unknown type for `catalog` parameter: {type(catalog)}"
            raise TypeError(msg)
        else:
            if polars._utils.logging.verbose():
                eprint(f"{fn_name}(): calling pyiceberg.catalog.load_catalog()")

            try:
                default_catalog = pyiceberg.catalog.load_catalog()

            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 ""
                )

View on GitHub (pinned to fe841f959e)