pola-rs/polars · error · RuntimeError

f"table named not found in sheet " if n_tables else f"no…

Error message

f"table named {table_name!r} not found in sheet {sheet_name!r}" if n_tables else f"no named tables found in sheet {sheet_name!r} (looking for {table_name!r})"

What it means

In the openpyxl engine, when `table_name` is requested the reader resolves the worksheet and looks for named tables; if the worksheet object is None (table/sheet lookup failed) it raises this RuntimeError — distinguishing between a sheet that has tables but not the requested one, and a sheet with no tables at all. It means the requested table cannot be found in the given sheet.

Solutions

1. Check the exact table name via openpyxl: `load_workbook(path)['Data'].tables.keys()`.
2. Pass the correct sheet_name where the table is defined.
3. Remove table_name and read the sheet range directly if no formal table exists.
4. Create a formal Excel table (Insert > Table) in the workbook if structured access is needed.

Example fix

// before
import openpyxl
wb = openpyxl.load_workbook('f.xlsx')
print(wb['Data'].tables)  # discover real names
// after
pl.read_excel('f.xlsx', engine='openpyxl', table_name='CorrectTableName', sheet_name='Data')

import openpyxl
ws = openpyxl.load_workbook(path)[sheet_name]
tables = dict(getattr(ws, 'tables', {}) or {})
if table_name not in tables:
    raise ValueError(f'tables in {sheet_name}: {list(tables)}')

try:
    df = pl.read_excel(path, engine='openpyxl', table_name=table_name, sheet_name=sheet_name)
except RuntimeError as e:
    if 'not found' in str(e):
        df = pl.read_excel(path, engine='openpyxl', sheet_name=sheet_name)
    else:
        raise

When it happens

Trigger: `pl.read_excel('f.xlsx', engine='openpyxl', table_name='Table1', sheet_name='Data')` where Data has tables but not Table1, or where the sheet/table lookup yields None and the sheet has no tables (n_tables == 0).

Common situations: Typo in table name; table defined on another sheet; workbook authored without formal Excel tables (just ranges), so no named tables exist.

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

• no named tables found in sheet
• table named not 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/44c181e2d88a3ca1. Report an issue: GitHub.

Appendix: source

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

    has_header = read_options.pop("has_header", True)
    schema_overrides = schema_overrides or {}
    no_inference = infer_schema_length == 0
    header: list[str | None] = []

    if table_name and not sheet_name:
        ws, sheet_name, n_tables = None, None, 0
        for sheet in parser.worksheets:
            n_tables += 1
            if table_name in sheet.tables:
                ws, sheet_name = sheet, sheet.title
                break
        if ws is None:
            msg = (
                f"table named {table_name!r} not found in sheet {sheet_name!r}"
                if n_tables
                else f"no named tables found in sheet {sheet_name!r} (looking for {table_name!r})"
            )
            raise RuntimeError(msg)
    else:
        ws = parser[sheet_name]

    # prefer detection of actual table objects; otherwise read
    # data in the used worksheet range, dropping null columns
    if tables := getattr(ws, "tables", None):
        table = tables[table_name] if table_name else next(iter(tables.values()))
        rows = list(ws[table.ref])
        if not rows:
            return _empty_frame(raise_if_empty)
        if has_header:
            header.extend(cell.value for cell in rows.pop(0))
        else:
            header.extend(f"column_{n}" for n in range(len(rows[0])))
        if table.totalsRowCount:
            rows = rows[: -table.totalsRowCount]
        rows_iter = rows
    elif table_name:

View on GitHub (pinned to fe841f959e)