{"record":{"id":"fd22504dc489e1fd","repo":"pola-rs/polars","slug":"cannot-specify-both-sheet-name-sheet-name-r","errorCode":null,"errorMessage":"cannot specify both `sheet_name` ({sheet_name!r}) and `sheet_id` ({sheet_id!r})","messagePattern":"cannot specify both `sheet_name` \\((.+?)\\) and `sheet_id` \\((.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/functions.py","lineNumber":794,"sourceCode":"        if \"has_header\" not in read_options:\n            read_options[\"has_header\"] = has_header\n    else:\n        read_options[\"infer_schema_length\"] = infer_schema_length\n        read_options[\"has_header\"] = has_header\n\n    return read_options\n\n\ndef _get_sheet_names(\n    sheet_id: int | Sequence[int] | None,\n    sheet_name: str | Sequence[str] | None,\n    table_name: str | None,\n    worksheets: list[dict[str, Any]],\n) -> tuple[list[str], bool]:\n    \"\"\"Establish sheets to read; indicate if we are returning a dict frames.\"\"\"\n    if sheet_id is not None and sheet_name is not None:\n        msg = f\"cannot specify both `sheet_name` ({sheet_name!r}) and `sheet_id` ({sheet_id!r})\"\n        raise ValueError(msg)\n\n    sheet_names = []\n    if sheet_id is None and sheet_name is None:\n        name = None if table_name else worksheets[0][\"name\"]\n        sheet_names.append(name)\n        return_multiple_sheets = False\n    elif sheet_id == 0:\n        sheet_names.extend(ws[\"name\"] for ws in worksheets)\n        return_multiple_sheets = True\n    else:\n        return_multiple_sheets = (\n            (isinstance(sheet_name, Sequence) and not isinstance(sheet_name, str))\n            or isinstance(sheet_id, Sequence)\n            or sheet_id == 0\n        )\n        if names := (\n            (sheet_name,) if isinstance(sheet_name, str) else sheet_name or ()\n        ):","sourceCodeStart":776,"sourceCodeEnd":812,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/io/spreadsheet/functions.py#L776-L812","documentation":"`read_excel` allows selecting sheets either by index (`sheet_id`) or by name (`sheet_name`), but not both at once, since the selections could disagree. `_get_sheet_names` raises a `ValueError` when both are non-None.","triggerScenarios":"`pl.read_excel(f, sheet_id=1, sheet_name='Sales')` or passing a non-default value for both parameters in any combination (ints, strings, or lists).","commonSituations":"Combining defaults from a wrapper function where each parameter defaults to a sentinel that became non-None; copy-pasted calls that accumulate parameters.","solutions":["Pass only `sheet_id` OR only `sheet_name`","Set one of them explicitly to None","If multiple selections are needed, pass a list to a single parameter (both accept lists)"],"exampleFix":"// before\npl.read_excel(f, sheet_id=1, sheet_name='Sales')\n// after\npl.read_excel(f, sheet_name='Sales')","handlingStrategy":"validation","validationCode":"assert sheet_id is None or sheet_name is None, 'pass sheet_id or sheet_name, not both'","typeGuard":null,"tryCatchPattern":"try:\n    df = pl.read_excel(f, sheet_id=sid, sheet_name=sname)\nexcept ValueError as e:\n    if 'cannot specify both' in str(e):\n        df = pl.read_excel(f, sheet_name=sname)\n    else:\n        raise","preventionTips":["Default both to None in wrappers, never to sentinel values","Choose one sheet-selection convention per codebase","Use lists on a single parameter for multi-sheet reads"],"tags":["python","polars","mutually-exclusive","excel"],"backgroundTag":"mutually-exclusive-options","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}