{"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":897,"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":879,"sourceCodeEnd":915,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/io/spreadsheet/functions.py#L879-L915","documentation":"Raised by _initialise_spreadsheet_parser as a NotImplementedError when the engine string matches none of the supported values 'calamine', 'xlsx2csv', 'openpyxl'. read_excel's default is 'calamine' and read_ods always forces calamine internally, so in practice this means a misspelled or obsolete engine string was passed to read_excel at runtime (the parameter is a Literal type, so type checkers catch it statically).","triggerScenarios":"pl.read_excel(src, engine='calamel') (typo); engine='pyxlsb' or 'xlrd' — names of engines removed or never supported by this polars version; engine values read from config files that bypass static typing.","commonSituations":"Code written against an older polars whose engine set differed, run after an upgrade; engine selected dynamically from a settings file; autocomplete-induced typos.","solutions":["Fix the spelling: use 'calamine' (default), 'xlsx2csv', or 'openpyxl'","Type the variable as Literal['calamine','xlsx2csv','openpyxl'] so mypy/pyright rejects bad values at lint time","If you depended on a removed engine (e.g. pyxlsb), switch to 'calamine', which handles xlsb via fastexcel"],"exampleFix":"# before\npl.read_excel(src, engine='pyxlsb')  # removed/unsupported -> NotImplementedError\n\n# after\npl.read_excel(src, engine='calamine')  # fastexcel reads xlsb/xls/xlsx/ods","handlingStrategy":"type-guard","validationCode":"SUPPORTED_ENGINES = {'calamine', 'xlsx2csv', 'openpyxl'}\nif engine not in SUPPORTED_ENGINES:\n    raise ValueError(f'engine must be one of {sorted(SUPPORTED_ENGINES)}, got {engine!r}')\ndf = pl.read_excel(src, engine=engine)","typeGuard":"from typing import Literal, TypeGuard\n\nExcelEngine = Literal['calamine', 'xlsx2csv', 'openpyxl']\n\ndef is_excel_engine(value: str) -> TypeGuard[ExcelEngine]:\n    return value in {'calamine', 'xlsx2csv', 'openpyxl'}\n\nassert is_excel_engine(engine), f'unsupported engine: {engine!r}'","tryCatchPattern":null,"preventionTips":["Annotate engine variables as Literal['calamine','xlsx2csv','openpyxl'] so mypy/pyright reject typos statically","Validate engine strings coming from config files before use (they bypass static typing)","After polars upgrades, grep for removed engine names (e.g. 'pyxlsb') — calamine now covers those formats"],"tags":["polars","excel","engine","typo","version-migration","literal-type"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}