{"record":{"id":"c2e40f7b5809540f","repo":"pola-rs/polars","slug":"unrecognized-engine-engine-r","errorCode":null,"errorMessage":"unrecognized engine: {engine!r}","messagePattern":"unrecognized engine: (.+?)","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/io/spreadsheet/functions.py","lineNumber":902,"sourceCode":"        if reading_bytesio:\n            source = source.getvalue()  # type: ignore[union-attr]\n        elif isinstance(source, (BufferedReader, TextIOWrapper)):\n            if \"b\" not in source.mode:\n                msg = f\"file {source.name!r} must be opened in binary mode\"\n                raise OSError(msg)\n            elif (filename := source.name) and Path(filename).exists():\n                source = filename\n            else:\n                source = source.read()\n\n        parser = fastexcel.read_excel(source, **engine_options)\n        sheets = [\n            {\"index\": i + 1, \"name\": nm} for i, nm in enumerate(parser.sheet_names)\n        ]\n        return _read_spreadsheet_calamine, parser, sheets\n\n    msg = f\"unrecognized engine: {engine!r}\"\n    raise NotImplementedError(msg)\n\n\ndef _csv_buffer_to_frame(\n    csv: StringIO,\n    *,\n    separator: str,\n    read_options: dict[str, Any],\n    schema_overrides: SchemaDict | None,\n    drop_empty_rows: bool,\n    drop_empty_cols: bool,\n    raise_if_empty: bool,\n) -> pl.DataFrame:\n    \"\"\"Translate StringIO buffer containing delimited data as a DataFrame.\"\"\"\n    # handle (completely) empty sheet data\n    if csv.tell() == 0:\n        return _empty_frame(raise_if_empty)\n\n    # otherwise rewind the buffer and parse as csv","sourceCodeStart":884,"sourceCodeEnd":920,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/io/spreadsheet/functions.py#L884-L920","documentation":"Polars' `read_excel`/spreadsheet reader only supports a fixed set of engines ('calamine', 'openpyxl', 'xlsx2csv', 'pyxlsb', 'ods'). After dispatching through the engine-specific reader functions, any engine value that did not match falls through to this final guard in `_initialise_spreadsheet_parser`, which raises `NotImplementedError`. It means the requested engine is not a known/supported backend name.","triggerScenarios":"Calling `pl.read_excel(..., engine='xlsxwriter')`, a misspelled engine like `'openpyl'`, or passing a non-string value; also occurs when a custom string is passed to `read_ods`/`read_xls` wrappers that share `_read_spreadsheet`.","commonSituations":"Typo in the engine name; copying example code from another library (e.g. pandas' 'openpyxl' vs polars' engine list); passing a config value read from a YAML/JSON file that holds an unsupported engine string; confusion between writer engines (xlsxwriter) and reader engines.","solutions":["Set engine to one of the supported values: 'calamine' (default), 'openpyxl', 'xlsx2csv', 'pyxlsb', or 'ods'.","Check spelling/case of the engine string exactly as listed in the polars docs.","If the engine value comes from config, validate it against the supported set before calling read_excel.","Install the dependency required for the chosen engine (e.g. pip install fastexcel for 'calamine')."],"exampleFix":"// before\npl.read_excel('data.xlsx', engine='xlsxwriter')\n// after\npl.read_excel('data.xlsx', engine='calamine')  # or 'openpyxl', 'xlsx2csv', 'pyxlsb', 'ods'","handlingStrategy":"validation","validationCode":"SUPPORTED_ENGINES = {'calamine', 'openpyxl', 'xlsx2csv', 'pyxlsb', 'ods'}\nif engine not in SUPPORTED_ENGINES:\n    raise ValueError(f'engine must be one of {sorted(SUPPORTED_ENGINES)}, got {engine!r}')","typeGuard":"def is_valid_engine(engine: object) -> TypeGuard[str]:\n    return isinstance(engine, str) and engine in {'calamine', 'openpyxl', 'xlsx2csv', 'pyxlsb', 'ods'}","tryCatchPattern":"try:\n    df = pl.read_excel(path, engine=engine)\nexcept NotImplementedError as e:\n    log.error('Unsupported spreadsheet engine: %s', e)\n    df = pl.read_excel(path, engine='calamine')","preventionTips":["Keep engine names in a constant/set sourced from the docs","Validate config-provided engine values at startup","Prefer the default 'calamine' engine unless you need a specific backend"],"tags":["polars","excel","invalid-argument-value"],"backgroundTag":"invalid-enum-value","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"}