pola-rs/polars · error · ValueError

engine must be one of {'connectorx', 'adbc'}, got {engine!r}

Error message

engine must be one of {'connectorx', 'adbc'}, got {engine!r}

What it means

Raised by read_database_uri() when the engine argument is not 'connectorx' or 'adbc'. Only these two URI engines exist; None defaults to connectorx, anything else is rejected up front.

Source

Thrown at py-polars/src/polars/io/database/functions.py:532

            schema_overrides=schema_overrides,
            pre_execution_query=pre_execution_query,
        )
    elif engine == "adbc":
        if not isinstance(query, str):
            msg = f"only a single SQL query string is accepted for adbc, got a {qualified_type_name(query)!r} type"
            raise ValueError(msg)
        if pre_execution_query:
            msg = "the 'adbc' engine does not support use of `pre_execution_query`"
            raise ValueError(msg)
        return _read_sql_adbc(
            query,
            connection_uri=uri,
            schema_overrides=schema_overrides,
            execute_options=execute_options,
        )
    else:
        msg = f"engine must be one of {{'connectorx', 'adbc'}}, got {engine!r}"
        raise ValueError(msg)

View on GitHub (pinned to df599052da)

Solutions

1. Use engine='connectorx' (default) or engine='adbc'
2. Pass engine=None to get the default connectorx behaviour
3. For SQLAlchemy or driver connections, use pl.read_database() instead

Example fix

# before
pl.read_database_uri(q, uri, engine="sqlalchemy")

# after
pl.read_database_uri(q, uri, engine="connectorx")
# or for SQLAlchemy
pl.read_database(q, sqlalchemy_engine.connect())

VALID_ENGINES = {"connectorx", "adbc", None}
assert engine in VALID_ENGINES, f"engine must be one of {VALID_ENGINES}, got {engine!r}"

def is_valid_engine(engine: object) -> TypeGuard[str | None]:
    return engine is None or (isinstance(engine, str) and engine in {"connectorx", "adbc"})

When it happens

Trigger: pl.read_database_uri(query, uri, engine='sqlalchemy') or a typo like 'connector_x', 'ADBC' (case matters).

Common situations: Assuming the local database driver name (e.g. 'sqlalchemy', 'psycopg2') is a valid engine; refactors introducing typos; uppercase/lowercase inconsistencies.

Related errors

• the 'connectorx' engine does not support use of `execute_opt
• the 'adbc' engine does not support use of `pre_execution_que
• only a single SQL query string is accepted for adbc, got a {
• the given column-schema names do not match the data dictiona
• Pandas dataframe contains non-unique indices and/or column n

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