{"record":{"id":"606f0039cb0d0d32","repo":"apache/superset","slug":"error-reading-excel-file","errorCode":null,"errorMessage":"Error reading Excel file","messagePattern":"Error reading Excel file","errorType":"exception","errorClass":"DatabaseUploadFailed","httpStatus":422,"severity":"error","filePath":"superset/commands/database/uploaders/excel_reader.py","lineNumber":94,"sourceCode":"            \"skiprows\": self._options.get(\"skip_rows\", 0),\n            \"sheet_name\": self._options.get(\"sheet_name\", 0),\n            \"nrows\": self._options.get(\"rows_to_read\"),\n        }\n        if self._options.get(\"columns_read\"):\n            kwargs[\"usecols\"] = self._options.get(\"columns_read\")\n        try:\n            return pd.read_excel(**kwargs)\n        except (\n            pd.errors.ParserError,\n            pd.errors.EmptyDataError,\n            UnicodeDecodeError,\n            ValueError,\n        ) as ex:\n            raise DatabaseUploadFailed(\n                message=_(\"Parsing error: %(error)s\", error=str(ex))\n            ) from ex\n        except Exception as ex:\n            raise DatabaseUploadFailed(_(\"Error reading Excel file\")) from ex\n\n    def file_metadata(self, file: FileStorage) -> FileMetadata:\n        try:\n            excel_file = pd.ExcelFile(file)\n        except (ValueError, AssertionError) as ex:\n            raise DatabaseUploadFailed(\n                message=_(\"Excel file format cannot be determined\")\n            ) from ex\n\n        sheet_names = excel_file.sheet_names\n\n        result: FileMetadata = {\"items\": []}\n        for sheet in sheet_names:\n            df = excel_file.parse(sheet, nrows=ROWS_TO_READ_METADATA)\n            column_names = df.columns.tolist()\n            result[\"items\"].append(\n                {\n                    \"sheet_name\": sheet,","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/apache/superset/blob/f4587218dd19d046c3e4d00063e7d27f8a2ed354/superset/commands/database/uploaders/excel_reader.py#L76-L112","documentation":"Catch-all DatabaseUploadFailed ('Error reading Excel file') raised in ExcelReader._read_sheet_to_dataframe for exceptions outside the recognized tuple — most often openpyxl exceptions (InvalidFileException, UserWarning-turned-error, BadZipFile because .xlsx is a ZIP), OSError, or missing optional engine dependencies. The chained 'from ex' in server logs carries the actual cause.","triggerScenarios":"pd.read_excel on a file with the right extension but wrong internal format (an .xlsx that is actually HTML or a pre-2007 .xls renamed); openpyxl raising on malformed XML inside the workbook; xlrd/openpyxl not installed for the given format; memory exhaustion on huge workbooks.","commonSituations":"Systems exporting 'Excel' files that are really HTML tables or SpreadsheetML variants; files emailed/downloaded and lightly renamed; deployments missing pip extras for excel support; workbooks with extremely many rows blowing memory during load.","solutions":["Check server logs for the chained exception (from ex) — it names the engine-level failure","Verify the file truly is a workbook: python -c \"import openpyxl; openpyxl.load_workbook('data.xlsx')\"","Install/confirm the right engine (openpyxl for xlsx, xlrd for legacy xls) in the Superset environment","Re-export from the source system as a real .xlsx, or convert the HTML-table pseudo-Excel to CSV and use the CSV reader"],"exampleFix":"python -c \"import openpyxl; openpyxl.load_workbook('data.xlsx')\"\n# fails -> file is not a real workbook; re-export as genuine xlsx or CSV","handlingStrategy":"try-catch","validationCode":"import openpyxl\n\ndef workbook_loads(path: str) -> bool:\n    try:\n        openpyxl.load_workbook(path, read_only=True)\n        return True\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"except DatabaseUploadFailed:\n    log.exception(\"excel read failed\")  # chained cause shows engine-level failure\n    raise","preventionTips":["Install openpyxl (xlsx) / xlrd (legacy xls) engines","Re-export pseudo-Excel (HTML) files as real .xlsx","Avoid renaming non-Excel files to .xlsx"],"tags":["excel","openpyxl","file-upload","catch-all"],"backgroundTag":null,"analyzedSha":"f4587218dd19d046c3e4d00063e7d27f8a2ed354","analyzedAt":"2026-08-14T22:39:27.425Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}