pola-rs/polars · error · ValueError

cannot apply delta_table_version for table of type {data_sou

Error message

cannot apply delta_table_version 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:270-280). Catalog.read_table / scan-style entry points accept delta_table_version, but only for tables whose data_source_format is DELTA (that branch returns early via scan_delta). For any other format (PARQUET, CSV, JSON, UNITY_*) a non-None delta_table_version is meaningless — Delta time-travel metadata does not exist — so it is rejected instead of silently ignored.

Source

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

        )

        if data_source_format in ["DELTA", "DELTASHARING"]:
            from polars.io.delta import scan_delta

            return scan_delta(
                storage_location,
                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,
            )
        )

View on GitHub (pinned to df599052da)

Solutions

1. Drop delta_table_version for non-Delta tables (read the latest snapshot)
2. If time travel is required, ensure the table is actually a Delta table (DESCRIBE TABLE EXTENDED / format checks)
3. Make the wrapper conditional: pass version only when data_source_format == 'DELTA'

Example fix

# before
ldf = catalog.read_table('cat.ns.tbl', delta_table_version=2)  # table is PARQUET

# after
fmt = catalog.get_table('cat.ns.tbl').data_source_format
ldf = catalog.read_table('cat.ns.tbl', delta_table_version=2 if fmt == 'DELTA' else None)

def can_time_travel(table_info) -> bool:
    return str(table_info.data_source_format).endswith('DELTA')

When it happens

Trigger: catalog.read_table('cat.schema.tbl', delta_table_version=3) where the table's data_source_format is PARQUET/CSV/JSON rather than DELTA.

Common situations: Generic read wrappers that always forward a version flag; assuming all Unity Catalog tables are Delta; tables converted to Parquet/UNITY format between environments.

Related errors

• cannot apply delta_table_options 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
• index positions should be smaller than 2^32
• index positions should be greater than or equal to -2^32

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