apache/superset · error · IncorrectVersionError

{file_name} is not a valid file

Error message

{file_name} is not a valid file

What it means

Raised by the legacy v0 dataset YAML import loader when yaml.safe_load produces neither a dict nor a list — i.e. the YAML root is a scalar, None (empty file), or some other non-container value. Both recognized export shapes (CLI dict, UI list) are containers, so anything else is treated as 'not a valid file'.

Source

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

            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. Check the file is non-empty and actually YAML (yaml.safe_load it locally and confirm the result is a dict or list)
2. Re-download or regenerate the export bundle
3. If the file only holds comments or stray text, remove it from the bundle

import yaml
from pathlib import Path

for f in Path(bundle_dir).glob('**/*.yaml'):
    text = f.read_text()
    if not text.strip():
        raise ValueError(f'{f}: empty YAML file')
    cfg = yaml.safe_load(text)
    if not isinstance(cfg, (dict, list)):
        raise ValueError(f'{f}: YAML root must be a mapping or list, got {type(cfg).__name__}')

def has_valid_yaml_root(cfg: object) -> bool:
    """v0 loader accepts only dict (CLI) or list (UI) roots."""
    return isinstance(cfg, (dict, list))

from superset.commands.importers.exceptions import IncorrectVersionError
try:
    importer.run()
except IncorrectVersionError as ex:
    if 'not a valid file' in str(ex):
        # drop/fix the malformed file in the bundle, then re-run once
        ...

When it happens

Trigger: Importing a YAML file that is empty (safe_load returns None), contains only a scalar/string/number, or has a document structure whose root is not a mapping or sequence.

Common situations: Empty upload file, a 0-byte file from a failed download, a plain-text file renamed to .yaml, or a YAML containing only comments.

Related errors

• {file_name} has no valid keys
• ; ".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/ee5529a61be40277. Report an issue: GitHub.