{"record":{"id":"68be2426a27f7d4d","repo":"pola-rs/polars","slug":"the-table-name-parameter-is-not-supported-by-the","errorCode":null,"errorMessage":"the `table_name` parameter is not supported by the 'xlsx2csv' engine","messagePattern":"the `table_name` parameter is not supported by the 'xlsx2csv' engine","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/functions.py","lineNumber":1314,"sourceCode":"    return df\n\n\ndef _read_spreadsheet_xlsx2csv(\n    parser: Any,\n    *,\n    sheet_name: str | None,\n    read_options: dict[str, Any],\n    schema_overrides: SchemaDict | None,\n    columns: Sequence[int] | Sequence[str] | None,\n    table_name: str | None = None,\n    drop_empty_rows: bool,\n    drop_empty_cols: bool,\n    raise_if_empty: bool,\n) -> pl.DataFrame:\n    \"\"\"Use the 'xlsx2csv' library to read data from the given worksheet.\"\"\"\n    if table_name:\n        msg = \"the `table_name` parameter is not supported by the 'xlsx2csv' engine\"\n        raise ValueError(msg)\n\n    csv_buffer = StringIO()\n    with warnings.catch_warnings():\n        # xlsx2csv version 0.8.4 throws a DeprecationWarning in Python 3.13\n        # https://github.com/dilshod/xlsx2csv/pull/287\n        warnings.filterwarnings(\"ignore\", category=DeprecationWarning)\n        parser.convert(outfile=csv_buffer, sheetname=sheet_name)\n\n    read_options.setdefault(\"truncate_ragged_lines\", True)\n    if columns:\n        read_options[\"columns\"] = columns\n\n    cast_to_boolean = []\n    if schema_overrides:\n        for col, dtype in schema_overrides.items():\n            if dtype == Boolean:\n                schema_overrides[col] = UInt8  # type: ignore[index]\n                cast_to_boolean.append(F.col(col).cast(Boolean))","sourceCodeStart":1296,"sourceCodeEnd":1332,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/spreadsheet/functions.py#L1296-L1332","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Switch to engine='calamine' (fastexcel >= 0.12) or engine='openpyxl', both of which support table_name","If you must stay on xlsx2csv, drop table_name and address the data via sheet_name/columns","Make wrapper functions omit table_name when the selected engine does not support it"],"exampleFix":"# before\npl.read_excel(src, engine='xlsx2csv', table_name='Sales')\n\n# after\npl.read_excel(src, engine='openpyxl', table_name='Sales')\n# or: pl.read_excel(src, engine='calamine', table_name='Sales')  # needs fastexcel>=0.12","handlingStrategy":"validation","validationCode":"TABLE_CAPABLE_ENGINES = {'calamine', 'openpyxl'}\nif table_name and engine == 'xlsx2csv':\n    engine = 'openpyxl'  # pick an engine that can actually read Excel Tables\n    # note: 'calamine' additionally needs fastexcel >= 0.12 for table_name\n\ndf = pl.read_excel(src, engine=engine, table_name=table_name)","typeGuard":"from typing import TypeGuard\n\ndef engine_supports_tables(engine: str) -> TypeGuard[str]:\n    return engine in {'calamine', 'openpyxl'}","tryCatchPattern":"try:\n    df = pl.read_excel(src, engine='xlsx2csv', table_name=tbl)\nexcept ValueError as e:\n    if 'table_name' in str(e) and 'xlsx2csv' in str(e):\n        df = pl.read_excel(src, engine='openpyxl', table_name=tbl)\n    else:\n        raise","preventionTips":["Know each engine's surface: xlsx2csv = plain sheet ranges only; tables require calamine (fastexcel>=0.12) or openpyxl","Make wrapper APIs drop or reject table_name when the caller selects xlsx2csv","When engine choice is driven by other options (e.g. truncate_ragged_lines), resolve table reads on a separate code path"],"tags":["polars","excel","xlsx2csv","table","unsupported-engine"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}