apache/superset · error · IncorrectVersionError

{file_name} has no valid keys

Error message

{file_name} has no valid keys

What it means

Raised by the legacy (v0) dataset YAML import loader when the parsed YAML is a mapping (CLI-export format) but does not contain the required top-level 'databases' key. It is wrapped as IncorrectVersionError because the v0 importer expects exports produced by the old CLI export command, whose schema is keyed by DATABASES_KEY. A YAML file that parses fine but was exported in a different format therefore fails schema-shape validation.

Source

Thrown at superset/commands/dataset/importers/v0.py:311

                    dataset["database_id"] = database.id
                    SqlaTable.import_from_dict(dataset, sync=self.sync)

    def validate(self) -> None:
        # ensure all files are YAML
        for file_name, content in self.contents.items():
            try:
                config = yaml.safe_load(content)
            except yaml.YAMLError as ex:
                logger.exception("Invalid YAML file")
                raise IncorrectVersionError(
                    f"{file_name} is not a valid YAML file"
                ) from ex

            # CLI export
            if isinstance(config, dict):
                # TODO (betodealmeida): validate with Marshmallow
                if DATABASES_KEY not in config:
                    raise IncorrectVersionError(f"{file_name} has no valid keys")

            # UI export
            elif isinstance(config, list):
                # TODO (betodealmeida): validate with Marshmallow
                pass

            else:
                raise IncorrectVersionError(f"{file_name} is not a valid file")

            self._configs[file_name] = config

View on GitHub (pinned to f4587218dd)

Solutions

1. Re-export the bundle with the matching export version (v1 export for v1 import) so the YAML schema matches the importer
2. Inspect the YAML root: the v0 CLI format requires a top-level 'databases' key; add it or use the file that has it
3. If importing via API, ensure the file goes under 'datasets/' in the bundle so the v1 importer (which expects a list) handles it instead of v0

Example fix

# before: YAML root lacks the key
some_column: ...
# after (v0 CLI format)
databases:
  - database_name: examples
    ...

import yaml
DatabasesKey = 'databases'
with open(path) as f:
    cfg = yaml.safe_load(f)
if not isinstance(cfg, (dict, list)):
    raise ValueError(f'{path}: root must be a mapping (v0 CLI export) or list (v0 UI export)')
if isinstance(cfg, dict) and DatabasesKey not in cfg:
    raise ValueError(f'{path}: v0 CLI export requires a top-level "{DatabasesKey}" key — use the v1 import path for v1 bundles')

def is_v0_cli_export(cfg: object) -> bool:
    return isinstance(cfg, dict) and 'databases' in cfg

def is_v0_ui_export(cfg: object) -> bool:
    return isinstance(cfg, list)

from superset.commands.importers.exceptions import IncorrectVersionError
try:
    import_command.run()
except IncorrectVersionError as ex:
    # report the offending file to the uploader; do not retry — the bundle format is wrong
    logging.warning('Bad bundle: %s', ex)

When it happens

Trigger: Calling the import API or CLI import command with a YAML file whose root is a dict lacking the 'databases' key — e.g. a v1-format export (root is a 'dataset' mapping), a hand-written YAML, or a truncated/corrupted export bundle.

Common situations: Mixing export formats: user downloads a YAML from a newer Superset (v1 format with 'dataset' root) and imports it through the legacy v0 path; or the upload bundle is missing the databases.yaml file and a dataset YAML is misinterpreted.

Related errors

• {file_name} is not a valid file
• ; ".join(str(message) for message in ex.messages)
• Only the default catalog is supported for this connection
• Unsupported whisker type: ${whiskerOptions}
• Found invalid orderby options

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