{"record":{"id":"0d81c8efa4cfc2a1","repo":"github/spec-kit","slug":"could-not-query-extension-catalog-catalog-error","errorCode":null,"errorMessage":"Could not query extension catalog: {catalog_error}","messagePattern":"Could not query extension catalog: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/commands/init.py","lineNumber":140,"sourceCode":"            raise ValueError(f\"Directory not found: {source_path}\")\n        if not (source_path / \"extension.yml\").exists():\n            raise ValueError(f\"No extension.yml found in {source_path}\")\n        manifest = manager.install_from_directory(source_path, speckit_version)\n        return f\"{manifest.name} v{manifest.version} installed\"\n\n    # --- Bundled extension name or catalog ID ---\n    bundled_path = _locate_bundled_extension(ext_spec)\n    if bundled_path is not None:\n        if manager.registry.is_installed(ext_spec):\n            return \"already installed\"\n        manifest = manager.install_from_directory(bundled_path, speckit_version)\n        return f\"{manifest.name} v{manifest.version} installed\"\n\n    # Fall back to catalog\n    catalog = ExtensionCatalog(project_path)\n    ext_info, catalog_error = _resolve_catalog_extension(ext_spec, catalog, \"add\")\n    if catalog_error:\n        raise ValueError(f\"Could not query extension catalog: {catalog_error}\")\n    if not ext_info:\n        raise ValueError(f\"Extension '{ext_spec}' not found in bundled extensions or catalog\")\n\n    resolved_id = ext_info[\"id\"]\n    if resolved_id != ext_spec:\n        bundled_path = _locate_bundled_extension(resolved_id)\n        if bundled_path is not None:\n            if manager.registry.is_installed(resolved_id):\n                return \"already installed\"\n            manifest = manager.install_from_directory(bundled_path, speckit_version)\n            return f\"{manifest.name} v{manifest.version} installed\"\n\n    if ext_info.get(\"bundled\") and not ext_info.get(\"download_url\"):\n        from ..extensions import REINSTALL_COMMAND\n\n        raise ValueError(\n            f\"Extension '{resolved_id}' is bundled with spec-kit but not found in the installed package. \"\n            f\"Try reinstalling spec-kit: {REINSTALL_COMMAND}\"","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/commands/init.py#L122-L158","documentation":"Before an init extension can be treated as a catalog id, Spec Kit queries the active extension catalog stack. If catalog lookup returns an ExtensionError, init wraps it as `Could not query extension catalog: <detail>`. The nested detail identifies the actual catalog failure.","triggerScenarios":"`specify init --extension <id-or-name>` falls back to ExtensionCatalog and `_resolve_catalog_extension`; catalog configuration validation, fetching, caching, or payload validation raises ExtensionError.","commonSituations":"SPECKIT_CATALOG_URL points to an unreachable or invalid URL, project/user extension-catalogs.yml is malformed, a custom catalog serves invalid JSON, or a transient network failure prevents the catalog from loading.","solutions":["Read the detail after the colon; it names the failing catalog URL or validation problem.","Check network access and the URL, especially when SPECKIT_CATALOG_URL or extension-catalogs.yml overrides the defaults.","Validate the custom catalog JSON shape and the catalog configuration YAML.","Temporarily unset custom catalog overrides to confirm the default catalog works, then fix or replace the custom source.","Retry after transient network/proxy outages."],"exampleFix":"# before\nexport SPECKIT_CATALOG_URL=https://example.invalid/catalog.json\n\n# after\nexport SPECKIT_CATALOG_URL=https://example.com/catalog.json","handlingStrategy":"retry","validationCode":"from pathlib import Path\nfrom specify_cli.extensions import ExtensionCatalog, ExtensionError\n\ndef active_catalog_is_readable(project_root: Path) -> bool:\n    try:\n        ExtensionCatalog(project_root).search()\n        return True\n    except ExtensionError:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    _install_extension_during_init(project_path, ext_spec, version)\nexcept ValueError as exc:\n    if str(exc).startswith(\"Could not query extension catalog:\"):\n        retry_transient_catalog_lookup_or_report_nested_detail(exc)\n    else:\n        raise","preventionTips":["Validate SPECKIT_CATALOG_URL and extension-catalogs.yml in environment bootstrap scripts.","Keep catalog endpoints monitored and highly available.","Cache a known-good catalog response for controlled recovery after transient outages."],"tags":["init","extensions","catalog","network","configuration"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}