{"record":{"id":"2bf8859ed75d6078","repo":"apache/superset","slug":"excel-file-format-cannot-be-determined","errorCode":null,"errorMessage":"Excel file format cannot be determined","messagePattern":"Excel file format cannot be determined","errorType":"validation","errorClass":"DatabaseUploadFailed","httpStatus":422,"severity":"error","filePath":"superset/commands/database/uploaders/excel_reader.py","lineNumber":100,"sourceCode":"        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,\n                    \"column_names\": column_names,\n                }\n            )\n        return result\n","sourceCodeStart":82,"sourceCodeEnd":117,"githubUrl":"https://github.com/apache/superset/blob/f4587218dd19d046c3e4d00063e7d27f8a2ed354/superset/commands/database/uploaders/excel_reader.py#L82-L117","documentation":"DatabaseUploadFailed ('Excel file format cannot be determined') raised in ExcelReader.file_metadata when pd.ExcelFile(file) raises ValueError or AssertionError. pd.ExcelFile inspects the file content to choose an engine; ValueError is thrown when no engine recognizes the format ('Excel file format cannot be determined' is pandas' own message), AssertionError from older engine paths on mismatched content. This runs during the sheet/column preview step before upload.","triggerScenarios":"Uploading a file with an Excel extension whose content is not XLSX/XLS/ODS: HTML tables saved as .xls (common from web apps), CSV renamed to .xlsx, SpreadsheetML 2003 XML files, or password-protected workbooks.","commonSituations":"Banking/reporting portals offering 'Export to Excel' that actually emit HTML or flat SpreadsheetML; files double-renamed; LibreOffice exports in unusual formats; .xlsx files withDRM/protection that pandas cannot open.","solutions":["Open the file in a spreadsheet app and 'Save As' .xlsx (Office Open XML), then re-upload","If the file is actually HTML/tabular text, rename to .csv (or .xls->html check) and use the CSV upload path","Confirm with: python -c \"import pandas as pd; pd.ExcelFile('data.xlsx')\" — same error reproduces outside Superset","Remove workbook protection before uploading"],"exampleFix":"# detect the true type\nfile export.xls   # 'HTML document text' -> it is HTML\n# convert: open in Excel/LibreOffice -> Save As -> .xlsx, then upload","handlingStrategy":"validation","validationCode":"import pandas as pd\n\ndef excel_format_determinable(path: str) -> bool:\n    try:\n        pd.ExcelFile(path)\n        return True\n    except (ValueError, AssertionError):\n        return False","typeGuard":null,"tryCatchPattern":"except DatabaseUploadFailed as ex:\n    # 'cannot be determined' -> tell user to re-save as .xlsx or use CSV upload\n    raise UserHint('Re-save the file as a real .xlsx, or upload it as CSV') from ex","preventionTips":["Beware 'Export to Excel' buttons that emit HTML — check with `file export.xls`","Save As .xlsx (Office Open XML) from a spreadsheet app","Remove workbook protection before upload"],"tags":["excel","file-format","pandas","file-upload"],"backgroundTag":null,"analyzedSha":"f4587218dd19d046c3e4d00063e7d27f8a2ed354","analyzedAt":"2026-08-14T22:39:27.425Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}