Unexpected three-part table name; provide the database/catal

Error message

Unexpected three-part table name; provide the database/catalog ({catalog!r}) on the connection URI

What it means

Error "Unexpected three-part table name; provide the database/catalog ({catalog!r}) on the connection URI" thrown in pola-rs/polars.

Source

Thrown at py-polars/src/polars/dataframe/frame.py:4720

            engine_to_dispose: Engine | None = None
            sa_object: Connectable

            if isinstance(connection, str):
                sa_object = engine_to_dispose = create_engine(connection)
            elif isinstance(connection, Session):
                sa_object = connection.connection()
            elif isinstance(connection, Connectable):
                sa_object = connection
            else:
                msg = (
                    f"unrecognised connection type {qualified_type_name(connection)!r}"
                )
                raise TypeError(msg)

            catalog, db_schema, unpacked_table_name = unpack_table_name(table_name)
            if catalog:
                msg = f"Unexpected three-part table name; provide the database/catalog ({catalog!r}) on the connection URI"
                raise ValueError(msg)

            try:
                # ensure conversion to pandas uses the pyarrow extension array option
                # so that we can make use of the sql/db export *without* copying data
                res: int | None = self.to_pandas(
                    use_pyarrow_extension_array=True,
                ).to_sql(
                    name=unpacked_table_name,
                    schema=db_schema,
                    con=sa_object,
                    if_exists=if_table_exists,
                    index=False,
                    **(engine_options or {}),
                )
            finally:
                if engine_to_dispose is not None:
                    engine_to_dispose.dispose()

View on GitHub (pinned to df599052da)

When it happens

Trigger: Thrown at py-polars/src/polars/dataframe/frame.py:4720 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/a30744cb6b017fdb. Report an issue: GitHub.