pola-rs/polars · error · RuntimeError

table named {table_name!r} not found in sheet {sheet_name!r}

Error message

table named {table_name!r} not found in sheet {sheet_name!r}

What it means

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.

Source

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

                elif base_dtype == Boolean:
                    parser_dtypes[name] = "boolean"

        read_options["dtypes"] = parser_dtypes

    if fastexcel_version < (0, 11, 2):
        ws = parser.load_sheet_by_name(name=sheet_name, **read_options)
        df: pl.DataFrame = ws.to_polars()
    else:
        if table_name:
            if col_names := read_options.get("use_columns"):
                selected_col_names = set(col_names)
                read_options["use_columns"] = lambda col: col.name in selected_col_names

            xl_table = parser.load_table(table_name, **read_options)

            if sheet_name and sheet_name != xl_table.sheet_name:
                msg = f"table named {table_name!r} not found in sheet {sheet_name!r}"
                raise RuntimeError(msg)
            df = xl_table.to_polars()

        elif _PYARROW_AVAILABLE:
            # eager loading is faster / more memory-efficient, but requires pyarrow
            ws_arrow = parser.load_sheet_eager(sheet_name, **read_options)
            df = cast("pl.DataFrame", from_arrow(ws_arrow))
        else:
            ws_arrow = parser.load_sheet(sheet_name, **read_options)
            df = cast("pl.DataFrame", from_arrow(ws_arrow))

        if read_options.get("header_row", False) is None and not read_options.get(
            "column_names"
        ):
            df.columns = [f"column_{i}" for i in range(1, df.width + 1)]

    df = _drop_null_data(
        df,
        raise_if_empty=raise_if_empty,

View on GitHub (pinned to df599052da)

Solutions

1. Drop the sheet_name argument and let polars locate the table: pl.read_excel(src, table_name='Sales')
2. Or align sheet_name with the sheet that actually contains the table (check in Excel: Table Design tab)
3. To resolve table-to-sheet mappings programmatically, inspect the workbook with openpyxl before reading

Example fix

# before (table 'Sales' lives on sheet 'Data')
pl.read_excel(src, sheet_name='Summary', table_name='Sales')

# after
pl.read_excel(src, table_name='Sales')  # located wherever it is defined

import openpyxl

def table_sheet_map(path):
    with openpyxl.load_workbook(path, read_only=True) as wb:
        return {t: ws.title for ws in wb.worksheets for t in ws.tables}

tmap = table_sheet_map(src)
if 'Sales' not in tmap:
    raise KeyError(f"table 'Sales' not in workbook; available: {sorted(tmap)}")
# table_name is workbook-scoped: pass it WITHOUT sheet_name, or verify the pair
assert sheet_name in (None, tmap['Sales']), f"'Sales' lives on sheet {tmap['Sales']!r}, not {sheet_name!r}"
df = pl.read_excel(src, table_name='Sales')

try:
    df = pl.read_excel(src, sheet_name=name, table_name=tbl)
except RuntimeError as e:
    if 'not found in sheet' in str(e):
        df = pl.read_excel(src, table_name=tbl)  # let polars locate the table itself
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• a more recent version of `fastexcel` is required for 'table_
• cannot specify both `sheet_name` ({sheet_name!r}) and `sheet
• no matching sheet found when `sheet_name` is {name!r}
• no matching sheet found when `sheet_id` is {idx}
• `fastexcel` >= 0.10 is required to read bytes; found {module

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