github/spec-kit · error · IntegrationCatalogError

Catalog from {entry.url} is not valid UTF-8: {exc}

Error message

Catalog from {entry.url} is not valid UTF-8: {exc}

What it means

Error "Catalog from {entry.url} is not valid UTF-8: {exc}" thrown in github/spec-kit.

Source

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

                        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
    ) -> List[Dict[str, Any]]:
        """Fetch and merge integrations from all active catalogs.

        Catalogs are processed in the order returned by
        :meth:`get_active_catalogs`.  On conflicts, the first catalog in that
        order wins (lower numeric priority = higher precedence).  Each dict is
        annotated with ``_catalog_name`` and ``_install_allowed``.
        """
        import sys

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Re-save the remote catalog as UTF-8 JSON, or point the catalog entry at a valid UTF-8 catalog.

When it happens

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