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', HTTP 400) is raised by the dataset import dispatcher after every configured importer command declined the payload. Each importer is tried in order; a payload whose version key matches none of them (or that fails every importer's format check as 'wrong version') results in this catch-all. Importers that matched the version but failed content validation re-raise their own error instead.

Source

Thrown at superset/commands/dataset/importers/dispatcher.py:70

        # 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. Regenerate the bundle by exporting from a working Superset instance (CLI: `superset export-datasets` or the UI export) so the `version` metadata is correct.
  2. Open the ZIP/YAML and confirm each file has the expected top-level `version: "1.0"` key matching what the v1 importer accepts.
  3. Make sure you're posting to the right import endpoint for the payload's resource type (dataset bundles to /api/v1/dataset/import).
  4. If a version-matching file failed content validation, fix that specific error — it re-raises with details rather than reaching this catch-all.

Example fix

# dataset.yaml — before (missing version => no importer accepts it)
- table_name: sales
  columns: []

# after
version: "1.0"
- table_name: sales
  columns: []
Defensive patterns

Strategy: validation

Validate before calling

# Inspect a bundle before uploading: every YAML must carry a recognized version
import io, zipfile, yaml

ACCEPTED_VERSIONS = {"1.0", "2.0"}  # per-resource; datasets accept "1.0"

def bundle_versions(zip_bytes: bytes) -> list[str]:
    versions = []
    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as zf:
        for name in zf.namelist():
            if name.endswith((".yaml", ".yml")):
                versions.append(str(yaml.safe_load(zf.read(name)).get("version")))
    return versions  # all members must be in ACCEPTED_VERSIONS for the resource

Try / catch

from superset.commands.exceptions import CommandInvalidError
try:
    ImportDatasetsCommand(contents, {})
except CommandInvalidError as ex:
    if "Could not find a valid command" in str(ex):
        # no importer accepted the bundle: regenerate via export; do not blind-retry
        instruct_user_to_reexport()
    else:
        handle_content_validation_errors(ex)

Prevention

When it happens

Trigger: POST /api/v1/dataset/import with a ZIP/YAML bundle missing a recognized `version` field (e.g., no `version: "1.0"` per file or a wrong value); uploading a dashboard export to the dataset import endpoint; hand-edited YAML that dropped the version key.

Common situations: Mixing export formats between resources (database vs dataset vs dashboard bundles); exporting from a much older/newer Superset whose bundle version isn't accepted; hand-writing import files instead of exporting from a working instance.

Related errors

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