{"record":{"id":"d6ad0918cfcd3f0a","repo":"pola-rs/polars","slug":"table-named-table-name-r-not-found-in-sheet-she","errorCode":null,"errorMessage":"table named {table_name!r} not found in sheet {sheet_name!r}","messagePattern":"table named (.+?) not found in sheet (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/functions.py","lineNumber":1100,"sourceCode":"                elif base_dtype == Boolean:\n                    parser_dtypes[name] = \"boolean\"\n\n        read_options[\"dtypes\"] = parser_dtypes\n\n    if fastexcel_version < (0, 11, 2):\n        ws = parser.load_sheet_by_name(name=sheet_name, **read_options)\n        df: pl.DataFrame = ws.to_polars()\n    else:\n        if table_name:\n            if col_names := read_options.get(\"use_columns\"):\n                selected_col_names = set(col_names)\n                read_options[\"use_columns\"] = lambda col: col.name in selected_col_names\n\n            xl_table = parser.load_table(table_name, **read_options)\n\n            if sheet_name and sheet_name != xl_table.sheet_name:\n                msg = f\"table named {table_name!r} not found in sheet {sheet_name!r}\"\n                raise RuntimeError(msg)\n            df = xl_table.to_polars()\n\n        elif _PYARROW_AVAILABLE:\n            # eager loading is faster / more memory-efficient, but requires pyarrow\n            ws_arrow = parser.load_sheet_eager(sheet_name, **read_options)\n            df = cast(\"pl.DataFrame\", from_arrow(ws_arrow))\n        else:\n            ws_arrow = parser.load_sheet(sheet_name, **read_options)\n            df = cast(\"pl.DataFrame\", from_arrow(ws_arrow))\n\n        if read_options.get(\"header_row\", False) is None and not read_options.get(\n            \"column_names\"\n        ):\n            df.columns = [f\"column_{i}\" for i in range(1, df.width + 1)]\n\n    df = _drop_null_data(\n        df,\n        raise_if_empty=raise_if_empty,","sourceCodeStart":1082,"sourceCodeEnd":1118,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/spreadsheet/functions.py#L1082-L1118","documentation":"Raised as a RuntimeError in _read_spreadsheet_calamine (fastexcel >= 0.12 path) when a table with the given table_name WAS found in the workbook, but it lives in a different sheet than the sheet_name you also passed. parser.load_table() locates tables anywhere in the workbook, then polars asserts xl_table.sheet_name == sheet_name — so despite the wording, the table usually exists; it is just not in the sheet you named.","triggerScenarios":"pl.read_excel(src, table_name='Sales', sheet_name='Summary') where the Excel Table 'Sales' is defined on sheet 'Data'; workbooks that reuse the same table display name across tabs; code that assumes tables sit on the first sheet.","commonSituations":"Combining sheet_name + table_name 'for precision' when table_name alone is already unique workbook-wide; workbooks restructured upstream so a table moved to another tab.","solutions":["Drop the sheet_name argument and let polars locate the table: pl.read_excel(src, table_name='Sales')","Or align sheet_name with the sheet that actually contains the table (check in Excel: Table Design tab)","To resolve table-to-sheet mappings programmatically, inspect the workbook with openpyxl before reading"],"exampleFix":"# before (table 'Sales' lives on sheet 'Data')\npl.read_excel(src, sheet_name='Summary', table_name='Sales')\n\n# after\npl.read_excel(src, table_name='Sales')  # located wherever it is defined","handlingStrategy":"validation","validationCode":"import openpyxl\n\ndef table_sheet_map(path):\n    with openpyxl.load_workbook(path, read_only=True) as wb:\n        return {t: ws.title for ws in wb.worksheets for t in ws.tables}\n\ntmap = table_sheet_map(src)\nif 'Sales' not in tmap:\n    raise KeyError(f\"table 'Sales' not in workbook; available: {sorted(tmap)}\")\n# table_name is workbook-scoped: pass it WITHOUT sheet_name, or verify the pair\nassert sheet_name in (None, tmap['Sales']), f\"'Sales' lives on sheet {tmap['Sales']!r}, not {sheet_name!r}\"\ndf = pl.read_excel(src, table_name='Sales')","typeGuard":null,"tryCatchPattern":"try:\n    df = pl.read_excel(src, sheet_name=name, table_name=tbl)\nexcept RuntimeError as e:\n    if 'not found in sheet' in str(e):\n        df = pl.read_excel(src, table_name=tbl)  # let polars locate the table itself\n    else:\n        raise","preventionTips":["Prefer passing table_name alone — polars/fastexcel resolves it workbook-wide, which is usually what you want","When both arguments are needed, verify the table-sheet pairing with openpyxl first","Treat 'not found in sheet' from calamine as 'table is on a different tab', not 'table missing'"],"tags":["polars","excel","calamine","table","sheet-selection","workbook-structure"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}