apache/superset · error · CommandInvalidError

Could not find a valid command to import file

Error message

Could not find a valid command to import file

What it means

CommandInvalidError('Could not find a valid command to import file') raised by ImportCommandDispatcher.run (dispatcher.py:65) after iterating every registered import command and none accepting the bundle. Each importer is tried and skipped on IncorrectVersionError ('File not handled by command, skipping'); a matching version with a broken payload would instead raise from within the loop. Reaching line 65 means no importer recognized the bundle's version/metadata at all.

Source

Thrown at superset/commands/database/importers/dispatcher.py:65

        # iterate over all commands until we find a version that can
        # handle the contents
        for version in command_versions:
            command = version(self.contents, *self.args, **self.kwargs)
            try:
                command.run()
                return
            except IncorrectVersionError:
                logger.debug("File not handled by command, skipping")
            except (CommandInvalidError, ValidationError):
                # found right version, but file is invalid
                logger.info("Command failed validation")
                raise
            except Exception:
                # validation succeeded but something went wrong
                logger.exception("Error running import command")
                raise

        raise CommandInvalidError("Could not find a valid command to import file")

    def validate(self) -> None:
        pass

View on GitHub (pinned to f4587218dd)

Solutions

1. Unzip the bundle and inspect the top metadata YAML — check the type and version fields against what your target Superset version exports.
2. Re-export the bundle from a Superset version compatible with your target, or update the target instance.
3. Ensure you post to the endpoint matching the bundle's resource type (database bundles to /database/import/, datasets to /dataset/import/, etc.).
4. Re-zip so metadata.yaml sits at the archive root, if the bundle was repackaged by hand.

Example fix

# before: dataset bundle posted to the wrong endpoint
POST /api/v1/database/import/  (form-data: zipfile=<dataset_export.zip>)
# -> CommandInvalidError: Could not find a valid command to import file

# after: post to the matching endpoint
POST /api/v1/dataset/import/  (form-data: zipfile=<dataset_export.zip>)

import zipfile, yaml

def bundle_matches_resource(zip_path: str, resource_type: str) -> bool:
    with zipfile.ZipFile(zip_path) as zf:
        names = zf.namelist()
        if not any(n.endswith("metadata.yaml") for n in names):
            return False
        meta = yaml.safe_load(zf.read("metadata.yaml"))
        return meta.get("type") == resource_type

from superset.commands.importers.exceptions import CommandInvalidError

try:
    ImportCommandDispatcher("database", zip_stream, passwords).run()
except CommandInvalidError as ex:
    if "Could not find a valid command" in str(ex):
        # wrong bundle type/version for this endpoint: check metadata.yaml
        ...

When it happens

Trigger: POST /api/v1/database/import/ (or the import endpoint of another resource) with a ZIP whose main metadata YAML names an export type/version no registered importer claims — e.g. an export from a much newer/older Superset, a renamed export type, a hand-built ZIP, or a non-import file (yaml for datasets posted to the database import endpoint).

Common situations: Moving export bundles between Superset versions whose EXPORT_VERSION changed; uploading the wrong resource's bundle to an endpoint; editing the YAML inside the ZIP and breaking the type/version keys; zipping the directory wrong (missing top-level metadata.yaml).

Related errors

• Not a ZIP file
• No valid import files were found
• Could not find a valid command to import file
• Not a valid ZIP file
• ZIP file contains multiple file types

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