apache/superset · error · DatabaseUploadFailed

Parsing error: %(error)s

Error message

Parsing error: %(error)s

What it means

DatabaseUploadFailed ('Parsing error: <detail>') raised in ExcelReader._read_sheet_to_dataframe when pd.read_excel fails with pd.errors.ParserError, pd.errors.EmptyDataError, UnicodeDecodeError, or ValueError. Typical messages come from openpyxl/xlrd: 'Worksheet does not exist' (ValueError), empty sheet (EmptyDataError), or invalid cell content failing conversion (ValueError).

Source

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

            "na_values": self._options.get("null_values")
            if self._options.get("null_values")  # None if an empty list
            else None,
            "parse_dates": self._options.get("column_dates") or False,
            "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)

View on GitHub (pinned to f4587218dd)

Solutions

1. Match the embedded pandas message: 'Worksheet does not exist' means the sheet name is wrong — re-pick the sheet
2. Ensure the chosen sheet has data and a header row consistent with the column list
3. If columns_read is set, verify names exactly match the sheet's header cells
4. For .xls (legacy) files, convert to .xlsx or install the xlrd engine dependency

Example fix

python -c "import pandas as pd; print(pd.ExcelFile('data.xlsx').sheet_names)"
# confirms the exact sheet names to select in the upload dialog

import pandas as pd

def excel_sheet_ok(path: str, sheet: str, columns: list[str] | None = None) -> bool:
    xl = pd.ExcelFile(path)
    if sheet not in xl.sheet_names:
        return False
    cols = set(xl.parse(sheet, nrows=1).columns)
    return columns is None or set(columns) <= cols

except DatabaseUploadFailed as ex:
    if 'Worksheet' in str(ex):
        refresh sheet list and re-select
    else:
        report(str(ex))

When it happens

Trigger: Uploading an .xlsx/.xls where the selected sheet name is missing or was renamed; a sheet that is completely empty; specifying usecols (columns_read) with names absent from the sheet; mixed-type columns pandas cannot reconcile (ValueError).

Common situations: Users renaming/deleting sheets after the upload dialog listed them; selecting column names that include hidden whitespace; Excel exports with an empty first sheet; very old .xls files requiring xlrd while only openpyxl is installed (surfaces as ValueError about engine/format).

Related errors

• Excel file format cannot be determined
• 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/05bad40609534626. Report an issue: GitHub.