{"record":{"id":"0f6de73c4ce00c93","repo":"pola-rs/polars","slug":"no-matching-sheets-found-when-sheet-param-is","errorCode":null,"errorMessage":"no matching sheets found when `sheet_{param}` is {value!r}","messagePattern":"no matching sheets found when `sheet_(.+?)` is (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/functions.py","lineNumber":713,"sourceCode":"                sheet_name=name,\n                schema_overrides=schema_overrides,\n                read_options=read_options,\n                raise_if_empty=raise_if_empty,\n                columns=columns,\n                table_name=table_name,\n                drop_empty_rows=drop_empty_rows,\n                drop_empty_cols=drop_empty_cols,\n            )\n            for name in sheet_names\n        }\n    finally:\n        if hasattr(parser, \"close\"):\n            parser.close()\n\n    if not parsed_sheets:\n        param, value = (\"id\", sheet_id) if sheet_name is None else (\"name\", sheet_name)\n        msg = f\"no matching sheets found when `sheet_{param}` is {value!r}\"\n        raise ValueError(msg)\n\n    if include_file_paths:\n        workbook = source if isinstance(source, str) else \"in-mem\"\n        parsed_sheets = {\n            name: frame.with_columns(F.lit(workbook).alias(include_file_paths))\n            for name, frame in parsed_sheets.items()\n        }\n    if return_multiple_sheets:\n        return parsed_sheets\n    return next(iter(parsed_sheets.values()))\n\n\ndef _get_read_options(\n    read_options: dict[str, Any] | None,\n    *,\n    engine: ExcelSpreadsheetEngine,\n    columns: Sequence[int] | Sequence[str] | None,\n    infer_schema_length: int | None,","sourceCodeStart":695,"sourceCodeEnd":731,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/spreadsheet/functions.py#L695-L731","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["List the actual sheets first (e.g. via openpyxl: load_workbook(path, read_only=True).sheetnames) and use an exact name from that list.","Prefer positional sheet_id when names are unstable, and verify it is within range (1-based; sheets are numbered in load order).","If tabs may vary, select case-insensitively/trimmed by resolving the name yourself before calling read_excel.","Catch ValueError and surface which workbook failed when looping over many files."],"exampleFix":"# before\npl.read_excel('f.xlsx', sheet_name='sheet1')  # actual tab: 'Sheet1'\n\n# after\nfrom openpyxl import load_workbook\nnames = load_workbook('f.xlsx', read_only=True).sheetnames\npl.read_excel('f.xlsx', sheet_name=names[0])","handlingStrategy":"validation","validationCode":"from openpyxl import load_workbook\n\nsheetnames = load_workbook(path, read_only=True).sheetnames\nif sheet_name is not None and sheet_name not in sheetnames:\n    sheet_name = next((n for n in sheetnames if n.strip().lower() == sheet_name.strip().lower()), sheet_name)\nif sheet_id is not None and sheet_id > len(sheetnames):\n    sheet_id = None  # or raise with the available names in the message\npl.read_excel(path, sheet_name=sheet_name, sheet_id=sheet_id)","typeGuard":null,"tryCatchPattern":"try:\n    df = pl.read_excel(path, sheet_name=sheet_name)\nexcept ValueError as e:\n    if 'no matching sheets found' in str(e):\n        from openpyxl import load_workbook\n        names = load_workbook(path, read_only=True).sheetnames\n        raise ValueError(f'{sheet_name!r} not in {names}') from e\n    raise","preventionTips":["List sheetnames once and reference exact strings from that list.","Prefer sheet_id for programmatic access when tab names may be localized/renamed.","Never trust visible tab labels — copy names programmatically or trim/case-fold them."],"tags":["excel","spreadsheet","read-excel","sheet-selection","validation"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}