unexpected value for `if_table_exists`: {if_table_exists!r}

Error message

unexpected value for `if_table_exists`: {if_table_exists!r}

Choose one of {'fail', 'replace', 'append'}

What it means

Error "unexpected value for `if_table_exists`: {if_table_exists!r} Choose one of {'fail', 'replace', 'append'}" thrown in pola-rs/polars.

Source

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

                mode = "create"
            elif if_table_exists == "replace":
                if driver_manager_version < (0, 7):
                    msg = (
                        "`if_table_exists = 'replace'` requires ADBC version >= 0.7, "
                        f"found {driver_manager_str_version}"
                    )
                    raise ModuleUpgradeRequiredError(msg)
                mode = "replace"
            elif if_table_exists == "append":
                # 'append' inserts into an existing table; the table-existence
                # check below can upgrade this to 'create_append'.
                mode = "append"
            else:
                msg = (
                    f"unexpected value for `if_table_exists`: {if_table_exists!r}"
                    f"\n\nChoose one of {{'fail', 'replace', 'append'}}"
                )
                raise ValueError(msg)

            with (
                conn if can_close_conn else contextlib.nullcontext(),
                conn.cursor() as cursor,
            ):
                catalog, db_schema, unpacked_table_name = unpack_table_name(table_name)
                n_rows: int

                # Try to get the name and version of the underlying ADBC driver to help
                # with error messages and backwards compatibility

                # We can reliably introspect the underlying driver from a URI
                # We can also introspect instantiated connections when PyArrow is
                # installed. Otherwise, the underlying driver is unknown
                # Ref: https://github.com/apache/arrow-adbc/issues/2828
                if isinstance(connection, str):
                    adbc_module_name = _get_adbc_module_name_from_uri(connection)
                    adbc_driver = _import_optional_adbc_driver(

View on GitHub (pinned to df599052da)

When it happens

Trigger: Thrown at py-polars/src/polars/dataframe/frame.py:4540 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/1e9a7b042bf24c34. Report an issue: GitHub.