apache/superset · error · DatabaseUploadFailed

Error reading Excel file

Error message

Error reading Excel file

What it means

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.

Source

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

            "skiprows": self._options.get("skip_rows", 0),
            "sheet_name": self._options.get("sheet_name", 0),
            "nrows": self._options.get("rows_to_read"),
        }
        if self._options.get("columns_read"):
            kwargs["usecols"] = self._options.get("columns_read")
        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,

View on GitHub (pinned to f4587218dd)

Solutions

1. Check server logs for the chained exception (from ex) — it names the engine-level failure
2. Verify the file truly is a workbook: python -c "import openpyxl; openpyxl.load_workbook('data.xlsx')"
3. Install/confirm the right engine (openpyxl for xlsx, xlrd for legacy xls) in the Superset environment
4. Re-export from the source system as a real .xlsx, or convert the HTML-table pseudo-Excel to CSV and use the CSV reader

Example fix

python -c "import openpyxl; openpyxl.load_workbook('data.xlsx')"
# fails -> file is not a real workbook; re-export as genuine xlsx or CSV

import openpyxl

def workbook_loads(path: str) -> bool:
    try:
        openpyxl.load_workbook(path, read_only=True)
        return True
    except Exception:
        return False

except DatabaseUploadFailed:
    log.exception("excel read failed")  # chained cause shows engine-level failure
    raise

When it happens

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

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

Related errors

• Error reading CSV file
• Parsing error: %(error)s
• Excel file format cannot be determined
• Please choose at least one groupby
• Parsing error: %(error)s

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