github/spec-kit · error · ValueError

Could not query extension catalog: {catalog_error}

Error message

Could not query extension catalog: {catalog_error}

What it means

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.

Source

Thrown at src/specify_cli/commands/init.py:140

            raise ValueError(f"Directory not found: {source_path}")
        if not (source_path / "extension.yml").exists():
            raise ValueError(f"No extension.yml found in {source_path}")
        manifest = manager.install_from_directory(source_path, speckit_version)
        return f"{manifest.name} v{manifest.version} installed"

    # --- Bundled extension name or catalog ID ---
    bundled_path = _locate_bundled_extension(ext_spec)
    if bundled_path is not None:
        if manager.registry.is_installed(ext_spec):
            return "already installed"
        manifest = manager.install_from_directory(bundled_path, speckit_version)
        return f"{manifest.name} v{manifest.version} installed"

    # Fall back to catalog
    catalog = ExtensionCatalog(project_path)
    ext_info, catalog_error = _resolve_catalog_extension(ext_spec, catalog, "add")
    if catalog_error:
        raise ValueError(f"Could not query extension catalog: {catalog_error}")
    if not ext_info:
        raise ValueError(f"Extension '{ext_spec}' not found in bundled extensions or catalog")

    resolved_id = ext_info["id"]
    if resolved_id != ext_spec:
        bundled_path = _locate_bundled_extension(resolved_id)
        if bundled_path is not None:
            if manager.registry.is_installed(resolved_id):
                return "already installed"
            manifest = manager.install_from_directory(bundled_path, speckit_version)
            return f"{manifest.name} v{manifest.version} installed"

    if ext_info.get("bundled") and not ext_info.get("download_url"):
        from ..extensions import REINSTALL_COMMAND

        raise ValueError(
            f"Extension '{resolved_id}' is bundled with spec-kit but not found in the installed package. "
            f"Try reinstalling spec-kit: {REINSTALL_COMMAND}"

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Read the detail after the colon; it names the failing catalog URL or validation problem.
2. Check network access and the URL, especially when SPECKIT_CATALOG_URL or extension-catalogs.yml overrides the defaults.
3. Validate the custom catalog JSON shape and the catalog configuration YAML.
4. Temporarily unset custom catalog overrides to confirm the default catalog works, then fix or replace the custom source.
5. Retry after transient network/proxy outages.

Example fix

# before
export SPECKIT_CATALOG_URL=https://example.invalid/catalog.json

# after
export SPECKIT_CATALOG_URL=https://example.com/catalog.json

from pathlib import Path
from specify_cli.extensions import ExtensionCatalog, ExtensionError

def active_catalog_is_readable(project_root: Path) -> bool:
    try:
        ExtensionCatalog(project_root).search()
        return True
    except ExtensionError:
        return False

try:
    _install_extension_during_init(project_path, ext_spec, version)
except ValueError as exc:
    if str(exc).startswith("Could not query extension catalog:"):
        retry_transient_catalog_lookup_or_report_nested_detail(exc)
    else:
        raise

When it happens

Trigger: `specify init --extension <id-or-name>` falls back to ExtensionCatalog and `_resolve_catalog_extension`; catalog configuration validation, fetching, caching, or payload validation raises ExtensionError.

Common situations: 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.

Related errors

• Extension '{ext_spec}' not found in bundled extensions or ca
• Extension '{ext_spec}' is in the '{catalog_name}' catalog bu
• Failed to fetch catalog from {entry.url}: {e}
• Invalid JSON in catalog from {entry.url}: {e}
• Failed to fetch any extension catalog

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