apache/superset · error · DatabaseUploadSoftDeletedDatasetExistsError

A soft-deleted dataset (uuid %(uuid)s) already references th

Error message

A soft-deleted dataset (uuid %(uuid)s) already references this table. Restore it via POST /api/v1/dataset/%(uuid)s/restore before uploading, or upload to a different table name.

What it means

DatabaseUploadSoftDeletedDatasetExistsError is raised when DatasetDAO.find_soft_deleted_logical_duplicate finds a soft-deleted dataset whose database/schema/table tuple matches the upload target. Superset blocks silent shadow-dataset creation and tells you to restore the twin via POST /api/v1/dataset/<uuid>/restore or pick another table name.

Source

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

            # hidden row — permanently blocking its restore — or die on the
            # legacy unique constraint. Check BEFORE ``reader.read`` writes
            # the file's contents into the analytics database: that write is
            # outside this command's metadata transaction and would not roll
            # back. With SOFT_DELETE off, leftover soft-deleted rows are
            # visible to the lookup above, so this branch is never reached
            # for them (degraded-mode semantics, consistent with the create
            # paths).
            # Deferred import: daos.dataset pulls in views.base, which
            # circularly imports back into the commands package at app init
            # (same constraint documented in daos/dataset.py re: PR #40573).
            from superset.daos.dataset import (  # noqa: PLC0415
                DatasetDAO,
            )

            if soft_twin := DatasetDAO.find_soft_deleted_logical_duplicate(
                self._model, Table(self._table_name, self._schema)
            ):
                raise DatabaseUploadSoftDeletedDatasetExistsError(str(soft_twin.uuid))

        self._reader.read(self._file, self._model, self._table_name, self._schema)

        if not sqla_table:
            sqla_table = SqlaTable(
                table_name=self._table_name,
                database=self._model,
                database_id=self._model_id,
                editors=editors,
                schema=self._schema,
            )
            db.session.add(sqla_table)

        sqla_table.fetch_metadata()

    @staticmethod
    def _file_size_bytes(file: Any) -> Optional[int]:
        """

View on GitHub (pinned to f4587218dd)

Solutions

1. Restore the soft-deleted dataset first: POST /api/v1/dataset/<uuid>/restore (uuid is in the error message)
2. Or upload to a different table name
3. Or permanently purge the soft-deleted dataset if restore is not wanted

Example fix

// before
 UploadCommand(db_id, "sales", file, schema, reader).run()

// after
 # after restoring the dataset named in the error:
 # POST /api/v1/dataset/<uuid>/restore
 UploadCommand(db_id, "sales", file, schema, reader).run()

from sqlalchemy import Table
from superset.daos.dataset import DatasetDAO

twin = DatasetDAO.find_soft_deleted_logical_duplicate(
    database, Table(table_name, schema)
)
if twin:
    # restore it or choose another table name BEFORE uploading
    ...

try:
    UploadCommand(...).run()
except DatabaseUploadSoftDeletedDatasetExistsError as e:
    uuid = e.args[0]  # twin dataset uuid
    # POST /api/v1/dataset/<uuid>/restore, then retry
    ...

When it happens

Trigger: Uploading a CSV to a table whose dataset was previously 'deleted' in the UI (soft delete); re-uploading after a dataset cleanup.

Common situations: Users delete a dataset in Explore, then try to re-upload the same table; recycled table names after dataset pruning.

Related errors

• Dashboard cannot be restored because its slug is now used by
• Cannot delete a database whose only remaining datasets are s
• Table already exists. You can change your 'if table already
• A soft-deleted dataset (uuid %(uuid)s) already references th
• Dataset {existing.table_name!r} (uuid {config['uuid']}) cann

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