pola-rs/polars · error · ValueError

no matching sheets found when `sheet_{param}` is {value!r}

Error message

no matching sheets found when `sheet_{param}` is {value!r}

What it means

ValueError raised at the end of _read_spreadsheet: sheets were located in the workbook, but none matched the requested selection, leaving parsed_sheets empty. The message identifies the offending parameter — sheet_id (when sheet_name is None) or sheet_name. sheet_id counts sheets in load order; sheet_name must match exactly (case and whitespace included).

Source

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

                sheet_name=name,
                schema_overrides=schema_overrides,
                read_options=read_options,
                raise_if_empty=raise_if_empty,
                columns=columns,
                table_name=table_name,
                drop_empty_rows=drop_empty_rows,
                drop_empty_cols=drop_empty_cols,
            )
            for name in sheet_names
        }
    finally:
        if hasattr(parser, "close"):
            parser.close()

    if not parsed_sheets:
        param, value = ("id", sheet_id) if sheet_name is None else ("name", sheet_name)
        msg = f"no matching sheets found when `sheet_{param}` is {value!r}"
        raise ValueError(msg)

    if include_file_paths:
        workbook = source if isinstance(source, str) else "in-mem"
        parsed_sheets = {
            name: frame.with_columns(F.lit(workbook).alias(include_file_paths))
            for name, frame in parsed_sheets.items()
        }
    if return_multiple_sheets:
        return parsed_sheets
    return next(iter(parsed_sheets.values()))


def _get_read_options(
    read_options: dict[str, Any] | None,
    *,
    engine: ExcelSpreadsheetEngine,
    columns: Sequence[int] | Sequence[str] | None,
    infer_schema_length: int | None,

View on GitHub (pinned to df599052da)

Solutions

1. List the actual sheets first (e.g. via openpyxl: load_workbook(path, read_only=True).sheetnames) and use an exact name from that list.
2. Prefer positional sheet_id when names are unstable, and verify it is within range (1-based; sheets are numbered in load order).
3. If tabs may vary, select case-insensitively/trimmed by resolving the name yourself before calling read_excel.
4. Catch ValueError and surface which workbook failed when looping over many files.

Example fix

# before
pl.read_excel('f.xlsx', sheet_name='sheet1')  # actual tab: 'Sheet1'

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

from openpyxl import load_workbook

sheetnames = load_workbook(path, read_only=True).sheetnames
if sheet_name is not None and sheet_name not in sheetnames:
    sheet_name = next((n for n in sheetnames if n.strip().lower() == sheet_name.strip().lower()), sheet_name)
if sheet_id is not None and sheet_id > len(sheetnames):
    sheet_id = None  # or raise with the available names in the message
pl.read_excel(path, sheet_name=sheet_name, sheet_id=sheet_id)

try:
    df = pl.read_excel(path, sheet_name=sheet_name)
except ValueError as e:
    if 'no matching sheets found' in str(e):
        from openpyxl import load_workbook
        names = load_workbook(path, read_only=True).sheetnames
        raise ValueError(f'{sheet_name!r} not in {names}') from e
    raise

When it happens

Trigger: pl.read_excel('f.xlsx', sheet_name='Sheet1 ') (trailing space) or 'sheet1' (wrong case); pl.read_excel('f.xlsx', sheet_id=5) in a workbook with 3 sheets; name mismatches after a workbook was regenerated with localized/renamed tabs.

Common situations: Hard-coded sheet names breaking when upstream producers rename tabs or localize Excel ('Feuil1', 'Tabelle1'); whitespace copied from visible tab names; 0-vs-1-based indexing confusion for sheet_id; iterating expected sheet lists against a changed template.

Related errors

• no workbook found at path {src!r}
• no data found in the given workbook(s) and sheet(s)
• cannot specify both `columns` and `read_options["use_columns
• the values of `has_header` and `read_options["header_row"]`
• cannot specify both `infer_schema_length` and `read_options[

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