pola-rs/polars · error · ValueError

cannot apply delta_table_options for table of type

Error message

cannot apply delta_table_options for table of type {data_source_format}

What it means

`scan_table` raises ValueError when `delta_table_options` is provided for a table whose format is not Delta Lake. Delta reader options (e.g. version, timestamp-as-of style settings) only apply to Delta sources, so passing them for PARQUET/CSV/other formats is rejected rather than silently ignored.

Solutions

Only pass `delta_table_options` when the table format is DELTA — gate the kwargs on the detected format
Remove the option for non-Delta tables
Branch your scanning helper: one path for Delta (with options), one for other formats

Example fix

// before
pl.scan_unity_catalog_table("c", "s", "t", delta_table_options={"versionAsOf": 2})  # non-Delta
// after
opts = {"versionAsOf": 2} if fmt == "DELTA" else None
pl.scan_unity_catalog_table("c", "s", "t", delta_table_options=opts)

Defensive patterns

Strategy: validation

Validate before calling

info = client.get_table(catalog, ns, table)
if info.data_source_format != 'DELTA' and delta_table_options:
    raise ValueError('delta_table_options only apply to DELTA tables')

Type guard

def is_delta_format(fmt: str) -> bool:
    return fmt.upper() == 'DELTA'

Try / catch

try:
    lf = client.scan_table(c, n, t, delta_table_options=opts)
except ValueError as e:
    if 'delta_table_options' in str(e):
        lf = client.scan_table(c, n, t)
    else:
        raise

Prevention

Build scan kwargs conditionally based on the table format
Centralize option handling in a helper that inspects the format first
Avoid blanket reuse of one kwargs dict across all tables

When it happens

Trigger: Calling `scan_table(..., delta_table_options={...})` (or via scan_unity_catalog_table) against a table whose `data_source_format` is not DELTA.

Common situations: Reusing a scan-options dict built for Delta tables across heterogeneous tables; scripted scans that always pass the same kwargs regardless of table type.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

Thrown at py-polars/src/polars/catalog/unity/client.py:281

                version=delta_table_version,
                delta_table_options=delta_table_options,
                storage_options=storage_options,
                credential_provider=credential_provider,
            )

        if delta_table_version is not None:
            msg = (
                "cannot apply delta_table_version for table of type "
                f"{data_source_format}"
            )
            raise ValueError(msg)

        if delta_table_options is not None:
            msg = (
                "cannot apply delta_table_options for table of type "
                f"{data_source_format}"
            )
            raise ValueError(msg)

        return wrap_ldf(
            self._client.scan_table(
                catalog_name,
                namespace,
                table_name,
                credential_provider=credential_provider,
                cloud_options=storage_options,
            )
        )

    def write_table(
        self,
        df: DataFrame,
        catalog_name: str,
        namespace: str,
        table_name: str,
        *,

View on GitHub (pinned to fe841f959e)