github/spec-kit · error · IntegrationValidationError

Catalog config file {config_path} is corrupted (expected a m

Error message

Catalog config file {config_path} is corrupted (expected a mapping).

What it means

Error "Catalog config file {config_path} is corrupted (expected a mapping)." thrown in github/spec-kit.

Source

Thrown at src/specify_cli/integrations/catalog.py:419

        """
        url = url.strip()
        if not url:
            raise IntegrationValidationError("Catalog URL must be non-empty.")
        self._validate_catalog_url(url)
        config_path = self.project_root / ".specify" / self.CONFIG_FILENAME

        data: Dict[str, Any] = {"catalogs": []}
        if config_path.exists():
            try:
                raw = yaml.safe_load(config_path.read_text(encoding="utf-8"))
            except (yaml.YAMLError, OSError, UnicodeError) as exc:
                raise IntegrationValidationError(
                    f"Failed to read catalog config {config_path}: {exc}"
                ) from exc
            if raw is None:
                raw = {}
            if not isinstance(raw, dict):
                raise IntegrationValidationError(
                    f"Catalog config file {config_path} is corrupted "
                    "(expected a mapping)."
                )
            data = raw

        catalogs = data.get("catalogs", [])
        if not isinstance(catalogs, list):
            raise IntegrationValidationError(
                f"Catalog config {config_path} has invalid 'catalogs' value: "
                "must be a list."
            )

        # Validate each existing entry before mutating anything. Fail fast so
        # we don't silently preserve a corrupt sibling entry or derive a new
        # priority from a bogus value.
        existing_priorities: List[int] = []
        valid_catalog_count = 0
        for idx, cat in enumerate(catalogs):

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Fix the catalog config file so its top level is a mapping, or delete it to regenerate.

When it happens

Trigger: Thrown at src/specify_cli/integrations/catalog.py:419 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of github/spec-kit@bf88c9f9a8 (2026-08-14). Data as JSON: /api/errors/6691db7ff2261fe2. Report an issue: GitHub.