{"record":{"id":"d6725c73df878e66","repo":"pola-rs/polars","slug":"source","errorCode":null,"errorMessage":"{source}","messagePattern":"\\{source\\}","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/functions.py","lineNumber":837,"sourceCode":"                if (sheet_id == 0 or ws[\"index\"] in ids or ws[\"name\"] in names)\n            }\n            for idx in ids:\n                if (name := sheet_names_by_idx.get(idx)) is None:\n                    msg = f\"no matching sheet found when `sheet_id` is {idx}\"\n                    raise ValueError(msg)\n                sheet_names.append(name)\n\n    return sheet_names, return_multiple_sheets  # type: ignore[return-value]\n\n\ndef _initialise_spreadsheet_parser(\n    engine: str | None,\n    source: str | IO[bytes] | bytes,\n    engine_options: dict[str, Any],\n) -> tuple[Callable[..., pl.DataFrame], Any, list[dict[str, Any]]]:\n    \"\"\"Instantiate the indicated spreadsheet parser and establish related properties.\"\"\"\n    if isinstance(source, str) and not Path(source).exists():\n        raise FileNotFoundError(source)\n\n    if engine == \"xlsx2csv\":  # default\n        xlsx2csv = import_optional(\"xlsx2csv\")\n\n        # establish sensible defaults for unset options\n        for option, value in {\n            \"exclude_hidden_sheets\": False,\n            \"skip_empty_lines\": False,\n            \"skip_hidden_rows\": False,\n            \"floatformat\": \"%f\",\n        }.items():\n            engine_options.setdefault(option, value)\n\n        if isinstance(source, bytes):\n            source = BytesIO(source)\n\n        parser = xlsx2csv.Xlsx2csv(source, **engine_options)\n        sheets = parser.workbook.sheets","sourceCodeStart":819,"sourceCodeEnd":855,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/spreadsheet/functions.py#L819-L855","documentation":"Raised by pl.read_excel / pl.read_ods in _initialise_spreadsheet_parser as a plain builtin FileNotFoundError (message is just the path) when source is a str that does not exist on disk. The check runs before any engine is loaded, so no optional dependency error can mask it. Note the string is first normalized (e.g. ~ expansion) and URLs are fetched earlier, so this only concerns local filesystem paths.","triggerScenarios":"pl.read_excel('data/report.xlsx') when the relative path is wrong for the current working directory; a typo in the filename; a file that a previous pipeline step failed to write; paths read from config/env vars that are unset or stale.","commonSituations":"Scripts run from a different cwd than expected (cron, notebooks, Airflow workers), Windows/Unix path separator mixups, race conditions where the file is created after the read starts.","solutions":["Resolve and verify the path first: Path(source).expanduser().resolve() and check .exists()","Check your working directory (os.getcwd()) if the path is relative","If the file should have been produced by an earlier step, verify that step succeeded before reading"],"exampleFix":"# before\npl.read_excel('data/report.xlsx')\n\n# after\nfrom pathlib import Path\npath = Path('data/report.xlsx').expanduser().resolve()\nif not path.exists():\n    raise FileNotFoundError(f'missing input file: {path}')\npl.read_excel(path)","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\npath = Path(source).expanduser().resolve() if isinstance(source, str) else Path(source)\nif not path.is_file():\n    raise FileNotFoundError(f'input workbook not found: {path} (cwd={Path.cwd()})')\ndf = pl.read_excel(path)","typeGuard":null,"tryCatchPattern":"try:\n    df = pl.read_excel(src)\nexcept FileNotFoundError:\n    # plain builtin exception; polars' message is just the path\n    log.error('workbook missing: %s', src)\n    raise","preventionTips":["Resolve paths to absolute (expanduser().resolve()) before handing them to read_excel","In scheduled jobs/notebooks, assert the cwd or use absolute paths from config","Validate that the producing pipeline step wrote the file (size > 0) before reading"],"tags":["polars","excel","file-not-found","filesystem","paths"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}