invoke-ai/InvokeAI · critical · ValueError

Attempted migration of unsupported `models.yaml` v{yaml_vers

Error message

Attempted migration of unsupported `models.yaml` v{yaml_version}. Only v3.0.0 is supported. Exiting.

What it means

During one-time migration of the legacy models.yaml (invoked from start()), the service requires the file's __metadata__.version to be exactly '3.0.0'. Any other version string raises ValueError telling the user only v3.0.0 is supported for automatic migration.

Source

Thrown at invokeai/app/services/model_install/model_install_default.py:703

        db_models = self.record_store.all_models()

        legacy_models_yaml_path = (
            self._app_config.legacy_models_yaml_path or self._app_config.root_path / "configs" / "models.yaml"
        )

        # The old path may be relative to the root path
        if not legacy_models_yaml_path.exists():
            legacy_models_yaml_path = Path(self._app_config.root_path, legacy_models_yaml_path)

        if legacy_models_yaml_path.exists():
            with open(legacy_models_yaml_path, "rt", encoding=locale.getpreferredencoding()) as file:
                legacy_models_yaml = yaml.safe_load(file)

            yaml_metadata = legacy_models_yaml.pop("__metadata__")
            yaml_version = yaml_metadata.get("version")

            if yaml_version != "3.0.0":
                raise ValueError(
                    f"Attempted migration of unsupported `models.yaml` v{yaml_version}. Only v3.0.0 is supported. Exiting."
                )

            self._logger.info(
                f"Starting one-time migration of {len(legacy_models_yaml.items())} models from {str(legacy_models_yaml_path)}. This may take a few minutes."
            )

            if len(db_models) == 0 and len(legacy_models_yaml.items()) != 0:
                for model_key, stanza in legacy_models_yaml.items():
                    _, _, model_name = str(model_key).split("/")
                    model_path = Path(stanza["path"])
                    if not model_path.is_absolute():
                        model_path = self._app_config.models_path / model_path
                    model_path = model_path.resolve()

                    config = ModelRecordChanges(
                        name=model_name,
                        description=stanza.get("description"),

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Update InvokeAI to a version whose migration supports your models.yaml version, or first migrate to v3.0.0 with an intermediate release.
2. Manually migrate models by re-importing them through the UI/CLI (heuristic_import) into the new database-backed store.
3. Back up and remove/rename the legacy models.yaml if you no longer need migration, then reinstall models.
4. Restore __metadata__.version to '3.0.0' only if you are certain the file truly is v3.0.0 and the key was accidentally edited.

Example fix

// before (models.yaml)
__metadata__:
  version: 2.0.0
// after
# migrate via intermediate InvokeAI release, or remove legacy models.yaml and re-import models via UI/CLI

import yaml
with open(models_yaml_path) as f:
    meta = yaml.safe_load(f).get('__metadata__', {})
if meta.get('version') != '3.0.0':
    raise SystemExit(f'Legacy models.yaml is v{meta.get("version")}; migrate to v3.0.0 first')

When it happens

Trigger: models.yaml with a version other than '3.0.0' (e.g. v2 edited by hand, or a newer schema) present in the models_path on startup; corrupted or hand-edited __metadata__ block; copying an old models.yaml from a different InvokeAI version.

Common situations: Upgrading across several InvokeAI versions so the YAML predates the supported schema; manually editing models.yaml and breaking the version key; mixing config directories from different installs.

Related errors

• Failed to load and migrate v3 config file {config_path}: {e}
• Failed to load config file {config_path}: {e}
• str(e)
• Multiuser mode is disabled. Authentication is not required i
• Multiuser mode is disabled. Admin setup is not required in s

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/db6a13f868d84a70. Report an issue: GitHub.