pola-rs/polars · error · RuntimeError

table named not found in sheet

Error message

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

What it means

With the calamine engine, `load_table` looks up the named table workbook-wide; if the resolved table's sheet differs from the requested `sheet_name`, polars raises this RuntimeError because the table named `table_name` does not exist within that specific sheet. The table name may exist elsewhere in the workbook.

Solutions

1. Remove `sheet_name` (or pass the table's actual sheet) so the table is located on its own sheet.
2. List available tables per sheet (openpyxl: ws.tables) to find where the table lives.
3. Verify the exact table name and its sheet in Excel (Formulas > Name Manager).

Example fix

// before
pl.read_excel('f.xlsx', engine='calamine', table_name='SalesTable', sheet_name='Raw')
// after
pl.read_excel('f.xlsx', engine='calamine', table_name='SalesTable')  # or sheet_name='Data' where the table lives

import openpyxl
wb = openpyxl.load_workbook(path, read_only=False)
found = [(s, t) for s in wb.sheetnames for t in wb[s].tables]
if (sheet_name, table_name) not in found:
    raise ValueError(f'{table_name!r} not on {sheet_name!r}; available: {found}')

try:
    df = pl.read_excel(path, engine='calamine', table_name=table_name, sheet_name=sheet_name)
except RuntimeError as e:
    if 'not found in sheet' in str(e):
        df = pl.read_excel(path, engine='calamine', table_name=table_name)  # search workbook-wide
    else:
        raise

When it happens

Trigger: `pl.read_excel('f.xlsx', engine='calamine', table_name='Table1', sheet_name='Sheet2')` where Table1 actually lives on Sheet1; passing a sheet_name that doesn't match the table's parent sheet.

Common situations: Assuming table names are global; workbook reorganized so tables moved sheets; copy-pasted sheet_name from a different workbook version.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• f"table named not found in sheet " if n_tables else f"no…
• no named tables found in sheet
• cannot create a second
• cannot specify both `columns` and `read_options["columns"]`
• cannot specify both `columns` and…

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

Appendix: source

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

                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(df.width)]

    df = _drop_null_data(
        df,
        raise_if_empty=raise_if_empty,

View on GitHub (pinned to fe841f959e)