apache/superset · error · DatabaseUploadFailed

Database upload file failed

Error message

Database upload file failed

What it means

DatabaseUploadFailed is the generic wrapper for any exception during the dataframe-to-SQL write in BaseUploader; the message is taken from ex.message when present, otherwise str(ex). It is the catch-all failure mode for file uploads beyond the specific guard clauses.

Source

Thrown at superset/commands/database/uploaders/base.py:140

            ):
                to_sql_kwargs["index_label"] = self._options.get("index_label")
            database.db_engine_spec.df_to_sql(
                database,
                data_table,
                df,
                to_sql_kwargs=to_sql_kwargs,
            )
        except ValueError as ex:
            raise DatabaseUploadFailed(
                message=_(
                    "Table already exists. You can change your "
                    "'if table already exists' strategy to append or "
                    "replace or provide a different Table Name to use."
                )
            ) from ex
        except Exception as ex:
            message = ex.message if hasattr(ex, "message") and ex.message else str(ex)
            raise DatabaseUploadFailed(message=message, exception=ex) from ex


class UploadCommand(BaseCommand):
    def __init__(  # pylint: disable=too-many-arguments
        self,
        model_id: int,
        table_name: str,
        file: Any,
        schema: Optional[str],
        reader: BaseDataReader,
    ) -> None:
        self._model_id = model_id
        self._model: Optional[Database] = None
        self._table_name = table_name
        self._schema = schema
        self._file = file
        self._reader = reader

View on GitHub (pinned to f4587218dd)

Solutions

1. Read the propagated message and the chained exception (exception=ex) in logs
2. Fix data-level issues (dtypes, nulls, encoding) or target-table constraints it names
3. If it is actually the exists-conflict, switch the if-exists strategy (see the 'Table already exists' variant)

try:
    UploadCommand(...).run()
except DatabaseUploadFailed as e:
    original = e.exception  # chained cause
    logger.error("upload failed: %s", original)
    # branch on original type (dtype, permissions, network)
    ...

When it happens

Trigger: Any non-ValueError exception from df_to_sql: dtype inference failures, constraint violations, driver errors, oversized payloads, permission errors on the target schema.

Common situations: CSVs with mixed/inferable-bad dtypes, target-table schema mismatches, DB write privilege missing, network drops mid-upload.

Related errors

• Unexpected error occurred, please check your logs for detail
• Table already exists. You can change your 'if table already
• Database not found.
• Not a ZIP file
• Error: %(error)s

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