pola-rs/polars · error · ValueError

no matching sheet found when `sheet_name` is {name!r}

Error message

no matching sheet found when `sheet_name` is {name!r}

What it means

Raised by pl.read_excel / pl.read_ods in _get_sheet_names (a ValueError) when a requested sheet_name is not in the set of worksheet names reported by the parsing engine. Names are matched exactly (case-sensitive, whitespace-sensitive), and the list reflects what the engine sees — e.g. xlsx2csv excludes hidden sheets if you set engine_options={'exclude_hidden_sheets': True}. Validation happens per name, so the first unknown name aborts the whole read.

Source

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

        sheet_names.append(name)
        return_multiple_sheets = False
    elif sheet_id == 0:
        sheet_names.extend(ws["name"] for ws in worksheets)
        return_multiple_sheets = True
    else:
        return_multiple_sheets = (
            (isinstance(sheet_name, Sequence) and not isinstance(sheet_name, str))
            or isinstance(sheet_id, Sequence)
            or sheet_id == 0
        )
        if names := (
            (sheet_name,) if isinstance(sheet_name, str) else sheet_name or ()
        ):
            known_sheet_names = {ws["name"] for ws in worksheets}
            for name in names:
                if name not in known_sheet_names:
                    msg = f"no matching sheet found when `sheet_name` is {name!r}"
                    raise ValueError(msg)
                sheet_names.append(name)
        else:
            ids = (sheet_id,) if isinstance(sheet_id, int) else sheet_id or ()
            sheet_names_by_idx = {
                idx: ws["name"]
                for idx, ws in enumerate(worksheets, start=1)
                if (sheet_id == 0 or ws["index"] in ids or ws["name"] in names)
            }
            for idx in ids:
                if (name := sheet_names_by_idx.get(idx)) is None:
                    msg = f"no matching sheet found when `sheet_id` is {idx}"
                    raise ValueError(msg)
                sheet_names.append(name)

    return sheet_names, return_multiple_sheets  # type: ignore[return-value]


def _initialise_spreadsheet_parser(

View on GitHub (pinned to df599052da)

Solutions

1. List the real sheet names first (openpyxl.load_workbook(path, read_only=True).sheetnames) and pass one of those
2. Fix the typo / exact casing / trailing whitespace in sheet_name
3. If sheets vary across inputs, read all sheets with sheet_id=0 and work from the returned dict keys
4. If the sheet is hidden, drop exclude_hidden_sheets from engine_options or unhide it in the source file

Example fix

# before
pl.read_excel('f.xlsx', sheet_name='Data ')  # trailing space -> ValueError

# after
import openpyxl
names = openpyxl.load_workbook('f.xlsx', read_only=True).sheetnames
pl.read_excel('f.xlsx', sheet_name=names[0])

import openpyxl

def sheet_names(path):
    with openpyxl.load_workbook(path, read_only=True) as wb:
        return list(wb.sheetnames)

names = sheet_names('report.xlsx')
target = 'Data'
if target not in names:  # exact, case-sensitive match as polars does
    target = next((n for n in names if n.strip() == target.strip()), None)
assert target, f'sheet {target!r} not in {names}'
df = pl.read_excel('report.xlsx', sheet_name=target)

def known_sheet_name(name: str, path: str) -> bool:
    with openpyxl.load_workbook(path, read_only=True) as wb:
        return name in wb.sheetnames

try:
    df = pl.read_excel(src, sheet_name=name)
except ValueError as e:
    if 'no matching sheet' in str(e):
        frames = pl.read_excel(src, sheet_id=0, infer_schema_length=1)  # discover real names
        raise ValueError(f'available sheets: {list(frames)}') from e
    raise

When it happens

Trigger: pl.read_excel('f.xlsx', sheet_name='sheet1') when the workbook has 'Sheet1'; sheet_name=['Data','Summary'] where 'Summary' does not exist; naming a hidden sheet after enabling exclude_hidden_sheets; names with trailing spaces copied from Excel.

Common situations: Workbooks regenerated by an upstream process with renamed/reordered tabs; locale-dependent sheet names; hardcoded names in ETL jobs; Excel sheet names that differ from the visible tab label after trailing-space trimming.

Related errors

• cannot specify both `sheet_name` ({sheet_name!r}) and `sheet
• no matching sheet found when `sheet_id` is {idx}
• a more recent version of `fastexcel` is required for 'schema
• table named {table_name!r} not found in sheet {sheet_name!r}
• can only call `.row()` without "index" or "by_predicate" val

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