github/spec-kit · error · IntegrationCatalogError

Failed to fetch catalog from {entry.url}: {exc}

Error message

Failed to fetch catalog from {entry.url}: {exc}

What it means

Error "Failed to fetch catalog from {entry.url}: {exc}" thrown in github/spec-kit.

Source

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

            try:
                self.cache_dir.mkdir(parents=True, exist_ok=True)
                cache_file.write_text(json.dumps(catalog_data, indent=2), encoding="utf-8")
                cache_meta.write_text(
                    json.dumps(
                        {
                            "cached_at": datetime.now(timezone.utc).isoformat(),
                            "catalog_url": entry.url,
                        },
                        indent=2,
                    ),
                    encoding="utf-8",
                )
            except OSError:
                pass  # Cache is best-effort; proceed with fetched data
            return catalog_data

        except urllib.error.URLError as exc:
            raise IntegrationCatalogError(
                f"Failed to fetch catalog from {entry.url}: {exc}"
            )
        except UnicodeDecodeError as exc:
            # A non-UTF-8 response body fails at .decode() before json.loads()
            # ever runs, so JSONDecodeError below does not cover it (the two are
            # sibling ValueError subclasses, not parent/child). Without this the
            # raw UnicodeDecodeError escapes _get_merged_integrations()'s
            # "warn and skip this catalog" handler and kills the whole command.
            raise IntegrationCatalogError(
                f"Catalog from {entry.url} is not valid UTF-8: {exc}"
            )
        except json.JSONDecodeError as exc:
            raise IntegrationCatalogError(
                f"Invalid JSON in catalog from {entry.url}: {exc}"
            )

    def _get_merged_integrations(
        self, force_refresh: bool = False

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Check network connectivity and the catalog URL and credentials, then retry fetching the catalog.

When it happens

Trigger: Thrown at src/specify_cli/integrations/catalog.py:237 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/e2950282804c1b29. Report an issue: GitHub.