apache/superset · error · ImportFailedError

Dashboard cannot be restored via re-import because its slug

Error message

Dashboard cannot be restored via re-import because its slug {effective_slug!r} is now used by another active dashboard. Upload a YAML with a different slug, or rename the active dashboard, and retry.

What it means

ImportFailedError is raised in the v1 restore branch when the effective slug (from the bundle's config, falling back to the existing row's slug) is now claimed by another active dashboard, per DashboardDAO.validate_update_slug_uniqueness. A partial unique index on active dashboards' slugs would otherwise turn the restore into an opaque IntegrityError on Postgres/MySQL 8.0.13+, so the check runs before the row is touched, leaving it untouched on failure.

Source

Thrown at superset/commands/dashboard/importers/v1/utils.py:389

            # config as field updates on the existing object, preserving the PK.
            # Same active-slug-twin check as the explicit restore
            # (``RestoreDashboardCommand``): the common re-import carries the
            # pre-deletion slug, which another active dashboard may have
            # claimed during the soft-deleted window. Check the *effective*
            # post-restore slug BEFORE mutating the row: the validation query
            # triggers the session's autoflush, so if the row were already
            # marked restored, the flush would emit the ``deleted_at = NULL``
            # UPDATE mid-validation and hit the partial unique index as an
            # opaque IntegrityError-wrapped import failure on exactly the
            # dialects (Postgres / MySQL 8.0.13+) this readable error exists
            # for. Checking first also leaves the row untouched on failure.
            effective_slug = config.get("slug", existing.slug)
            if effective_slug is not None and not (
                DashboardDAO.validate_update_slug_uniqueness(
                    existing.id, effective_slug
                )
            ):
                raise ImportFailedError(
                    f"Dashboard cannot be restored via re-import because its "
                    f"slug {effective_slug!r} is now used by another active "
                    f"dashboard. Upload a YAML with a different slug, or "
                    f"rename the active dashboard, and retry."
                )
            existing.restore()
            # Apply the incoming slug to the existing row before flushing. On
            # the partial-index dialects (Postgres / MySQL 8.0.13+) the
            # active-slug constraint sees the row's post-flush state. If the old
            # slug was claimed by another active dashboard while this one was
            # soft-deleted, the operator resolves it by uploading a YAML with a
            # different (safe) slug — the flush below must reflect that change,
            # or the implicit-restore path fails on the stale DB slug even
            # though the upload was supposed to fix it.
            if "slug" in config:
                existing.slug = config["slug"]
            db.session.flush()
            config["id"] = existing.id

View on GitHub (pinned to f4587218dd)

Solutions

Edit the bundle's dashboard YAML and set a different, unused slug, then re-zip and re-import.
Or rename the active dashboard currently holding the slug (or clear its slug), then retry the import unchanged.
Or omit the slug in the bundle only if the existing soft-deleted row's slug is itself free — otherwise one of the two rows must change.

Example fix

# before
# bundle YAML: slug: sales  (active dashboard 'Sales FY26' already owns 'sales')
client.post('/api/v1/dashboard/import/', ...)

# after
# dashboard_DATA.yaml -> slug: sales-legacy
# re-zip and import; or PUT /api/v1/dashboard/{active_id} json={'slug': 'sales-fy26'} first

Defensive patterns

Strategy: validation

Validate before calling

from superset.daos.dashboard import DashboardDAO

effective_slug = bundle_config.get('slug') or existing.slug
if effective_slug and not DashboardDAO.validate_update_slug_uniqueness(existing.id, effective_slug):
    bundle_config['slug'] = f"{effective_slug}-restored-{uuid4().hex[:4]}"
    repackage_bundle()

Try / catch

try:
    run_import(bundle)
except ImportFailedError as ex:
    if 'slug' in str(ex) and 'another active dashboard' in str(ex):
        rewrite_bundle_slug_and_retry()

Prevention

Namespace slugs per team/purpose (e.g. 'sales-fy25-legacy') to avoid collisions.
Before restoring by import, check the slug is free with validate_update_slug_uniqueness.
When reusing short slugs, expect conflicts and automate slug rewriting in pipelines.

When it happens

Trigger: Re-importing a soft-deleted dashboard whose slug was re-used by a new active dashboard: another team created a dashboard with the same slug between the soft-delete and the re-import attempt.

Common situations: Deleted dashboards whose slugs were later reclaimed; environment sync pipelines re-pushing old bundles into an environment where the short slug was taken; copy workflows that reuse human-friendly slugs like 'sales'.

Related errors

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