pola-rs/polars · error · ValueError

engine must be one of

Error message

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

What it means

read_database_uri only accepts engine values 'connectorx' or 'adbc'. Any other string falls into the final else branch and raises ValueError. Use read_database with a connection object for other drivers (e.g. sqlalchemy-based engines).

Solutions

1. Pass engine='connectorx' or engine='adbc' exactly (lowercase)
2. Use pl.read_database with a DBAPI2/sqlalchemy connection for other engines
3. Check the installed engine extra: pip install 'polars[connectorx]' or 'polars[adbc]'

Example fix

// before
pl.read_database_uri('SELECT * FROM t', uri, engine='sqlalchemy')
// after
pl.read_database_uri('SELECT * FROM t', uri, engine='connectorx')

ALLOWED = {'connectorx', 'adbc'}
if engine not in ALLOWED:
    raise ValueError(f'engine must be one of {ALLOWED}, got {engine!r}')

try:
    df = pl.read_database_uri(q, uri, engine=engine)
except ValueError as e:
    if 'engine must be one of' in str(e):
        df = pl.read_database(q, connection=conn)

When it happens

Trigger: pl.read_database_uri(query, uri, engine='psycopg') or any misspelled/other engine string.

Common situations: Typo like 'ConnectorX' or 'Connectorx' (case-sensitive), or passing an engine name valid for read_database (e.g. 'sqlalchemy') to read_database_uri instead.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Cannot set `iter_batches` for
• Cannot set `iter_batches` without also setting a non-zero…
• invalid alignment
• invalid engine
• invalid table format name

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

Appendix: source

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

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