{"record":{"id":"152d7c3b670a8458","repo":"pola-rs/polars","slug":"invalid-table-style-key-key-r","errorCode":null,"errorMessage":"invalid table style key: {key!r}","messagePattern":"invalid table style key: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/_write_utils.py","lineNumber":556,"sourceCode":"    return table_columns, column_formats, df  # type: ignore[return-value]\n\n\ndef _xl_setup_table_options(\n    table_style: dict[str, Any] | str | None,\n) -> tuple[dict[str, Any] | str | None, dict[str, Any]]:\n    \"\"\"Setup table options, distinguishing style name from other formatting.\"\"\"\n    if isinstance(table_style, dict):\n        valid_options = (\n            \"style\",\n            \"banded_columns\",\n            \"banded_rows\",\n            \"first_column\",\n            \"last_column\",\n        )\n        for key in table_style:\n            if key not in valid_options:\n                msg = f\"invalid table style key: {key!r}\"\n                raise ValueError(msg)\n\n        table_options = table_style.copy()\n        table_style = table_options.pop(\"style\", None)\n    else:\n        table_options = {}\n\n    return table_style, table_options\n\n\n@overload\ndef _xl_worksheet_in_workbook(\n    wb: Workbook, ws: Worksheet, *, return_worksheet: Literal[False] = ...\n) -> bool: ...\n@overload\ndef _xl_worksheet_in_workbook(\n    wb: Workbook, ws: Worksheet, *, return_worksheet: Literal[True]\n) -> Worksheet: ...\n","sourceCodeStart":538,"sourceCodeEnd":574,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/spreadsheet/_write_utils.py#L538-L574","documentation":"ValueError raised by _xl_setup_table_options during write_excel when table_style is a dict containing an unrecognized key. The dict form accepts exactly five keys — 'style', 'banded_columns', 'banded_rows', 'first_column', 'last_column' (mirroring Excel's table style options); anything else is a typo or an option that belongs elsewhere.","triggerScenarios":"pl.write_excel(df, table_style={'style': 'Table Style Medium 9', 'banded_cols': True}) — misspelled 'banded_columns'; or keys like 'stripe_rows', 'style_name', 'autofilter' that are not part of the API.","commonSituations":"Hand-writing the options dict from memory of the Excel UI instead of the polars docs; translating openpyxl/xlsxwriter option names into this dict; version drift after the dict-based table_style interface was introduced.","solutions":["Correct the key name: use only 'style', 'banded_columns', 'banded_rows', 'first_column', 'last_column'.","If you meant the style name itself, pass table_style='Table Style Medium 9' as a plain string.","Keep a frozenset of the valid keys and validate config dicts against it before calling write_excel."],"exampleFix":"# before\npl.write_excel(df, table_style={'style': 'Table Style Medium 9', 'band_rows': True})\n\n# after\npl.write_excel(df, table_style={'style': 'Table Style Medium 9', 'banded_rows': True})","handlingStrategy":"validation","validationCode":"VALID_TABLE_STYLE_KEYS = {'style', 'banded_columns', 'banded_rows', 'first_column', 'last_column'}\nif isinstance(table_style, dict):\n    bad = set(table_style) - VALID_TABLE_STYLE_KEYS\n    if bad:\n        raise ValueError(f'invalid table_style keys: {sorted(bad)}; valid: {sorted(VALID_TABLE_STYLE_KEYS)}')\npl.write_excel(df, table_style=table_style)","typeGuard":"def is_valid_table_style(ts: object) -> bool:\n    if isinstance(ts, str):\n        return True\n    return isinstance(ts, dict) and set(ts) <= {'style', 'banded_columns', 'banded_rows', 'first_column', 'last_column'}","tryCatchPattern":"try:\n    pl.write_excel(df, table_style=table_style)\nexcept ValueError as e:\n    if 'invalid table style key' in str(e):\n        cleaned = {k: v for k, v in table_style.items() if k in VALID_TABLE_STYLE_KEYS} if isinstance(table_style, dict) else table_style\n        pl.write_excel(df, table_style=cleaned)\n    else:\n        raise","preventionTips":["Memorize the five keys: style, banded_columns, banded_rows, first_column, last_column.","Pass a plain string when only the style name is needed.","Define table_style dicts as module constants so typos surface in one reviewed place."],"tags":["excel","spreadsheet","write-excel","table-style","parameter-validation"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}