pola-rs/polars · error · ValueError

the `table_name` parameter is not supported by the 'xlsx2csv

Error message

the `table_name` parameter is not supported by the 'xlsx2csv' engine

What it means

Raised as a ValueError at the top of _read_spreadsheet_xlsx2csv when the table_name parameter is used with engine='xlsx2csv'. The xlsx2csv engine streams sheets to CSV and has no concept of Excel Table objects, so polars rejects the combination up front rather than silently ignoring the parameter. Use the calamine or openpyxl engines to read named tables.

Source

Thrown at py-polars/src/polars/io/spreadsheet/functions.py:1314

    return df


def _read_spreadsheet_xlsx2csv(
    parser: Any,
    *,
    sheet_name: str | None,
    read_options: dict[str, Any],
    schema_overrides: SchemaDict | None,
    columns: Sequence[int] | Sequence[str] | None,
    table_name: str | None = None,
    drop_empty_rows: bool,
    drop_empty_cols: bool,
    raise_if_empty: bool,
) -> pl.DataFrame:
    """Use the 'xlsx2csv' library to read data from the given worksheet."""
    if table_name:
        msg = "the `table_name` parameter is not supported by the 'xlsx2csv' engine"
        raise ValueError(msg)

    csv_buffer = StringIO()
    with warnings.catch_warnings():
        # xlsx2csv version 0.8.4 throws a DeprecationWarning in Python 3.13
        # https://github.com/dilshod/xlsx2csv/pull/287
        warnings.filterwarnings("ignore", category=DeprecationWarning)
        parser.convert(outfile=csv_buffer, sheetname=sheet_name)

    read_options.setdefault("truncate_ragged_lines", True)
    if columns:
        read_options["columns"] = columns

    cast_to_boolean = []
    if schema_overrides:
        for col, dtype in schema_overrides.items():
            if dtype == Boolean:
                schema_overrides[col] = UInt8  # type: ignore[index]
                cast_to_boolean.append(F.col(col).cast(Boolean))

View on GitHub (pinned to df599052da)

Solutions

1. Switch to engine='calamine' (fastexcel >= 0.12) or engine='openpyxl', both of which support table_name
2. If you must stay on xlsx2csv, drop table_name and address the data via sheet_name/columns
3. Make wrapper functions omit table_name when the selected engine does not support it

Example fix

# before
pl.read_excel(src, engine='xlsx2csv', table_name='Sales')

# after
pl.read_excel(src, engine='openpyxl', table_name='Sales')
# or: pl.read_excel(src, engine='calamine', table_name='Sales')  # needs fastexcel>=0.12

TABLE_CAPABLE_ENGINES = {'calamine', 'openpyxl'}
if table_name and engine == 'xlsx2csv':
    engine = 'openpyxl'  # pick an engine that can actually read Excel Tables
    # note: 'calamine' additionally needs fastexcel >= 0.12 for table_name

df = pl.read_excel(src, engine=engine, table_name=table_name)

from typing import TypeGuard

def engine_supports_tables(engine: str) -> TypeGuard[str]:
    return engine in {'calamine', 'openpyxl'}

try:
    df = pl.read_excel(src, engine='xlsx2csv', table_name=tbl)
except ValueError as e:
    if 'table_name' in str(e) and 'xlsx2csv' in str(e):
        df = pl.read_excel(src, engine='openpyxl', table_name=tbl)
    else:
        raise

When it happens

Trigger: pl.read_excel(src, engine='xlsx2csv', table_name='Sales'); also reached when a shared kwargs dict containing table_name is splatted into a read_excel call pinned to the xlsx2csv engine.

Common situations: Switching engines to xlsx2csv (e.g. for its truncate_ragged_lines handling) while keeping table-based reads; wrapper code that always passes table_name regardless of engine.

Related errors

• cannot specify both `columns` and `read_options["columns"]`
• the values of `has_header` and `read_options["has_header"]`
• cannot specify both `infer_schema_length` and `read_options[
• cannot specify columns in both `schema_overrides` and `read_
• a more recent version of `fastexcel` is required for 'table_

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