apache/superset · error · ImportFailedError

Import failed for an unknown reason

Error message

Import failed for an unknown reason

What it means

ImportFailedError raised from the PREVENT_UNSAFE_DB_CONNECTIONS check in importers/v1/utils.py: before creating/updating the imported database, make_url_safe(config['sqlalchemy_uri']) is passed to check_sqlalchemy_uri(); a SupersetSecurityException (blocked scheme/host) is re-raised as ImportFailedError(exc.message). When the security exception carries no message the ImportFailedError default text ('Import failed for an unknown reason') surfaces — the underlying cause is the URI being rejected as unsafe.

Source

Thrown at superset/commands/database/importers/v1/utils.py:63

    can_write = ignore_permissions or security_manager.can_access(
        "can_write",
        "Database",
    )
    existing = db.session.query(Database).filter_by(uuid=config["uuid"]).first()
    if existing:
        if not overwrite or not can_write:
            return existing
        config["id"] = existing.id
    elif not can_write:
        raise ImportFailedError(
            "Database doesn't exist and user doesn't have permission to create databases"  # noqa: E501
        )
    # Check if this URI is allowed (skip for system imports like examples)
    if app.config["PREVENT_UNSAFE_DB_CONNECTIONS"] and not ignore_permissions:
        try:
            check_sqlalchemy_uri(make_url_safe(config["sqlalchemy_uri"]))
        except SupersetSecurityException as exc:
            raise ImportFailedError(exc.message) from exc
    # https://github.com/apache/superset/pull/16756 renamed ``csv`` to ``file``.
    # Handle both old and new field names, defaulting to True for examples database
    if "allow_csv_upload" in config:
        config["allow_file_upload"] = config.pop("allow_csv_upload")
    elif "allow_file_upload" not in config:
        # Default to True for backward compatibility
        config["allow_file_upload"] = True

    if "schemas_allowed_for_csv_upload" in config.get("extra", {}):
        config["extra"]["schemas_allowed_for_file_upload"] = config["extra"].pop(
            "schemas_allowed_for_csv_upload"
        )

    # TODO (betodealmeida): move this logic to import_from_dict
    config["extra"] = json.dumps(config["extra"])

    # Convert masked_encrypted_extra → encrypted_extra before importing.
    # For existing DBs, reveal masked sensitive values from current encrypted_extra.

View on GitHub (pinned to f4587218dd)

Solutions

1. Identify the blocked URI: unzip the bundle and read the database YAML's sqlalchemy_uri.
2. Change the bundle to a permitted engine/host, or import the database separately with an approved URI and let the bundle resolve it by UUID.
3. If the destination is genuinely safe, have the operator adjust the policy (PREVENT_UNSAFE_DB_CONNECTIONS / allowed-hosts configuration) rather than bypassing it per-request — the check is skipped only for system imports (ignore_permissions).

Example fix

# before: bundle contains
# sqlalchemy_uri: sqlite:///examples.db
# PREVENT_UNSAFE_DB_CONNECTIONS=True -> ImportFailedError

# after: point the bundle at an approved server
# sqlalchemy_uri: postgresql://user:pass@dw.internal:5432/examples

from superset.utils.core import check_sqlalchemy_uri
from sqlalchemy.engine import make_url
from superset.exceptions import SupersetSecurityException

def uri_is_import_safe(uri: str) -> bool:
    try:
        check_sqlalchemy_uri(make_url(uri))
        return True
    except SupersetSecurityException:
        return False

from superset.commands.importers.exceptions import ImportFailedError

try:
    dispatcher.run()
except ImportFailedError:
    # when PREVENT_UNSAFE_DB_CONNECTIONS is on, inspect the bundle's URI and
    # either fix the bundle or have the operator adjust policy
    ...

When it happens

Trigger: POST /api/v1/database/import/ with PREVENT_UNSAFE_DB_CONNECTIONS=True (non-default) and a bundle whose sqlalchemy_uri uses a disallowed scheme (e.g. sqlite) or points at a host the check forbids (e.g. loopback/reserved ranges blocked by policy).

Common situations: Security-hardened deployments that enable PREVENT_UNSAFE_DB_CONNECTIONS; importing example/demo bundles that embed sqlite:// URIs; bundles authored on laptops with localhost databases.

Related errors

• Data URI is not allowed.
• SYNTAX_ERROR
• security_error
• Cannot convert node type: ${node.type}
• Please provide a JWT secret at least 32 bytes long

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