apache/superset · error · DatabaseUploadFailed

Excel file format cannot be determined

Error message

Excel file format cannot be determined

What it means

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.

Source

Thrown at superset/commands/database/uploaders/excel_reader.py:100

        try:
            return pd.read_excel(**kwargs)
        except (
            pd.errors.ParserError,
            pd.errors.EmptyDataError,
            UnicodeDecodeError,
            ValueError,
        ) as ex:
            raise DatabaseUploadFailed(
                message=_("Parsing error: %(error)s", error=str(ex))
            ) from ex
        except Exception as ex:
            raise DatabaseUploadFailed(_("Error reading Excel file")) from ex

    def file_metadata(self, file: FileStorage) -> FileMetadata:
        try:
            excel_file = pd.ExcelFile(file)
        except (ValueError, AssertionError) as ex:
            raise DatabaseUploadFailed(
                message=_("Excel file format cannot be determined")
            ) from ex

        sheet_names = excel_file.sheet_names

        result: FileMetadata = {"items": []}
        for sheet in sheet_names:
            df = excel_file.parse(sheet, nrows=ROWS_TO_READ_METADATA)
            column_names = df.columns.tolist()
            result["items"].append(
                {
                    "sheet_name": sheet,
                    "column_names": column_names,
                }
            )
        return result

View on GitHub (pinned to f4587218dd)

Solutions

1. Open the file in a spreadsheet app and 'Save As' .xlsx (Office Open XML), then re-upload
2. If the file is actually HTML/tabular text, rename to .csv (or .xls->html check) and use the CSV upload path
3. Confirm with: python -c "import pandas as pd; pd.ExcelFile('data.xlsx')" — same error reproduces outside Superset
4. Remove workbook protection before uploading

Example fix

# detect the true type
file export.xls   # 'HTML document text' -> it is HTML
# convert: open in Excel/LibreOffice -> Save As -> .xlsx, then upload

import pandas as pd

def excel_format_determinable(path: str) -> bool:
    try:
        pd.ExcelFile(path)
        return True
    except (ValueError, AssertionError):
        return False

except DatabaseUploadFailed as ex:
    # 'cannot be determined' -> tell user to re-save as .xlsx or use CSV upload
    raise UserHint('Re-save the file as a real .xlsx, or upload it as CSV') from ex

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Parsing error: %(error)s
• Parsing error: %(error)s
• Error reading CSV file
• Error reading Excel file
• Error reading Columnar file

AI-assisted analysis of apache/superset@f4587218dd (2026-08-14). Data as JSON: /api/errors/2bf8859ed75d6078. Report an issue: GitHub.