pola-rs/polars · error · ValueError

cannot apply delta_table_options for table of type {data_sou

Error message

cannot apply delta_table_options for table of type {data_source_format}

What it means

ValueError from the Unity Catalog scan path (py-polars/src/polars/catalog/unity/client.py:277-287). delta_table_options (extra options handed to the Delta scan engine, e.g. delta-specific reader configs) is only valid when data_source_format is DELTA; that path returns early via scan_delta. For PARQUET/CSV/JSON/UNITY tables the option dict has no consumer, so passing it raises rather than being silently dropped. Use storage_options for cloud credentials on non-Delta tables.

Source

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

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

Solutions

1. Remove delta_table_options for non-Delta tables
2. Pass cloud credentials via storage_options instead, which is supported for all formats
3. Gate Delta-specific options on data_source_format == 'DELTA' in wrapper code

Example fix

# before
ldf = catalog.read_table('cat.ns.tbl', delta_table_options=delta_cfg)  # PARQUET table

# after
ldf = catalog.read_table('cat.ns.tbl', storage_options=storage_cfg)

def split_table_options(fmt: str, delta_opts: dict | None, storage_opts: dict | None):
    if fmt != 'DELTA' and delta_opts:
        raise ValueError('delta_table_options only valid for DELTA tables')
    return delta_opts if fmt == 'DELTA' else None, storage_opts

When it happens

Trigger: catalog.read_table('cat.schema.tbl', delta_table_options={'delta.appendOnly': 'true'}) on a non-Delta table; generic option-forwarding wrappers that always populate delta_table_options.

Common situations: Copy-pasting a Delta read call onto a Parquet-backed table; conflating storage_options (cloud creds) with delta_table_options (Delta engine hints).

Related errors

• cannot apply delta_table_version for table of type {data_sou
• a non-HTTPS workspace_url was given ({workspace_url}). To al
• write_table: table format of {catalog_name}.{namespace}.{tab
• `{name}` is not supported by the remote engine
• index positions should be smaller than 2^32

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