{"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":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/functions.py","lineNumber":789,"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":771,"sourceCodeEnd":807,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/spreadsheet/functions.py#L771-L807","documentation":"Raised by polars.read_excel and pl.read_ods in _get_sheet_names (a ValueError) when both sheet_id and sheet_name are not None. Sheet selection is mutually exclusive by design: id-based and name-based selection cannot be combined, even when they point at the same sheet. This check runs before any worksheet data is parsed.","triggerScenarios":"pl.read_excel('f.xlsx', sheet_id=1, sheet_name='Sheet1'); pl.read_ods('f.ods', sheet_id=[1,2], sheet_name='data'); also fires when wrapper code computes both values from defaults and ends up passing neither as None.","commonSituations":"Config-driven loaders where sheet_id and sheet_name are both populated 'to be safe'; refactoring code from name-based to position-based selection while forgetting to remove the old argument; passing **kwargs dictionaries that carry both keys.","solutions":["Pass exactly one of sheet_id or sheet_name; explicitly set the other to None","In wrapper functions, resolve the config to a single selector before calling read_excel","Remember sheet_id is 1-based and 0 means 'all sheets' when choosing which side to keep"],"exampleFix":"# before\npl.read_excel('f.xlsx', sheet_id=1, sheet_name='Sheet1')\n\n# after\npl.read_excel('f.xlsx', sheet_name='Sheet1')","handlingStrategy":"validation","validationCode":"def resolve_sheet_selector(sheet_id, sheet_name):\n    if sheet_id is not None and sheet_name is not None:\n        raise ValueError('pass either sheet_id or sheet_name, not both')\n    return sheet_id, sheet_name\n\nsheet_id, sheet_name = resolve_sheet_selector(sheet_id, sheet_name)\ndf = pl.read_excel(src, sheet_id=sheet_id, sheet_name=sheet_name)","typeGuard":null,"tryCatchPattern":"try:\n    df = pl.read_excel(src, sheet_id=sheet_id, sheet_name=sheet_name)\nexcept ValueError as e:\n    if 'cannot specify both' in str(e):\n        df = pl.read_excel(src, sheet_name=sheet_name)  # keep one selector\n    else:\n        raise","preventionTips":["Resolve config down to exactly one of sheet_id / sheet_name before calling read_excel/read_ods","Remember sheet_id is 1-based and 0 means 'all sheets'","In **kwargs-based wrappers, drop whichever selector is None instead of passing both"],"tags":["polars","excel","ods","sheet-selection","parameters","mutually-exclusive"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}