apache/superset · error · DatabaseUploadFailed

Table already exists. You can change your 'if table already

Error 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.

What it means

DatabaseUploadFailed with the 'Table already exists' message is raised in BaseUploader when df_to_sql raises ValueError. It means the target table exists and the chosen 'if table already exists' strategy (mapped to pandas if_exists='fail') refuses to overwrite it.

Source

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

        try:
            data_table = Table(table=table_name, schema=schema_name)
            to_sql_kwargs = {
                "chunksize": READ_CHUNK_SIZE,
                "if_exists": self._options.get("already_exists", "fail"),
                "index": self._options.get("dataframe_index", False),
            }
            if self._options.get("index_label") and self._options.get(
                "dataframe_index"
            ):
                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],

View on GitHub (pinned to f4587218dd)

Solutions

Change the 'if table already exists' strategy to append or replace in the upload dialog
Or provide a different Table Name in the upload form
Drop/rename the existing table if a fresh load is intended

Example fix

// before
 options = {"if_exists": "fail"}

// after
 options = {"if_exists": "append"}  # or "replace"

Defensive patterns

Strategy: validation

Validate before calling

from sqlalchemy import inspect

with db_conn.get_sqla_engine() as engine:
    exists = inspect(engine).has_table(table_name, schema=schema)
if exists and strategy == "fail":
    raise ValueError("choose append/replace or a new table name")

Try / catch

try:
    UploadCommand(...).run()
except DatabaseUploadFailed as e:
    if "already exists" in str(e):
        # surface strategy choice to the user
        ...

Prevention

Pre-check table existence before upload
Default the dialog to append/replace for repeat loads

When it happens

Trigger: CSV/Excel upload to a table name that already exists in the schema while the strategy is set to 'fail' (the default append/replace not selected).

Common situations: Re-uploading the same file twice; uploading to a shared schema where a table with that name was created by someone else.

Related errors

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