apache/superset · error · DatabaseUploadFailed

Parsing error: %(error)s

Error message

Parsing error: %(error)s

What it means

DatabaseUploadFailed ('Parsing error: <UnicodeDecodeError detail>') raised in CSVReader._read_csv when pd.read_csv hits undecodable bytes AND the request explicitly set a non-default encoding (encoding != UTF-8 default). Because the user pinned the encoding, Superset does not attempt detection and surfaces the raw decode error, e.g. "'utf-8' codec can't decode byte 0xff in position 12".

Source

Thrown at superset/commands/database/uploaders/csv_reader.py:450

                        index_col = kwargs.get("index_col")
                        if isinstance(index_col, str):
                            result.index.name = index_col
                    df = result
            else:
                df = pd.read_csv(
                    filepath_or_buffer=file.stream,
                    **kwargs,
                )

            if types:
                df = CSVReader._cast_column_types(df, types, kwargs)

            return df
        except DatabaseUploadFailed:
            raise
        except UnicodeDecodeError as ex:
            if encoding != DEFAULT_ENCODING:
                raise DatabaseUploadFailed(
                    message=_("Parsing error: %(error)s", error=str(ex))
                ) from ex

            file.seek(0)
            detected_encoding = CSVReader._detect_encoding(file)
            if detected_encoding != encoding:
                kwargs["encoding"] = detected_encoding
                return CSVReader._read_csv(file, kwargs)
            raise DatabaseUploadFailed(
                message=_("Parsing error: %(error)s", error=str(ex))
            ) from ex
        except (
            pd.errors.ParserError,
            pd.errors.EmptyDataError,
            ValueError,
        ) as ex:
            raise DatabaseUploadFailed(
                message=_("Parsing error: %(error)s", error=str(ex))

View on GitHub (pinned to f4587218dd)

Solutions

1. Set encoding to match the file: run 'file -bi data.csv' (gives charset=...) and select that encoding
2. If unsure, omit the explicit encoding and let Superset's detection path retry (only available when encoding equals the default)
3. Re-save/export the CSV as UTF-8 from the source application

Example fix

file -bi data.csv
# charset=iso-8859-1 -> choose ISO-8859-1 in the upload dialog
# or in the source app: Save As -> 'CSV UTF-8'

def file_matches_encoding(path: str, encoding: str) -> bool:
    try:
        open(path, encoding=encoding).read(4096)
        return True
    except UnicodeDecodeError:
        return False

except DatabaseUploadFailed as ex:
    if 'codec' in str(ex):
        # wrong encoding selected: detect and retry with the reported charset
        ...

When it happens

Trigger: Selecting an encoding in the upload UI (e.g. utf-8, latin-1) that does not match the file's actual byte content: choosing utf-8 for a UTF-16/cp1252 file, or a single-byte encoding for a file containing multi-byte characters.

Common situations: Excel 'CSV UTF-8' vs plain 'CSV' exports (UTF-8 with BOM vs cp1252); files re-saved by editors in another encoding; explicit encoding chosen from a dropdown while the file was converted in between.

Related errors

• Error reading CSV file
• Table already exists. You can change your 'if table already
• Parsing error: %(error)s
• Error reading Columnar file
• Unexpected no file extension found

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