github/spec-kit · error · ValueError

Extension '{ext_spec}' not found in bundled extensions or ca

Error message

Extension '{ext_spec}' not found in bundled extensions or catalog

What it means

The extension argument was neither a URL, local path, nor a bundled extension, and catalog resolution found no matching id or unique display name. Spec Kit therefore raises ValueError and marks the init extension step failed.

Source

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

            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. Run `specify extension list --available` (or `specify extension search`) and copy the exact extension ID.
2. Retry `specify init <project> --extension <exact-id>`; IDs are case-sensitive.
3. If the extension is community/custom, configure a trusted catalog that actually contains it.
4. Otherwise install from a local directory or trusted URL using the ./path or https:// forms.

Example fix

# before
specify init demo --extension "Self Test"

# after
specify init demo --extension selftest

from pathlib import Path
from specify_cli.extensions import ExtensionCatalog

def extension_spec_resolves(ext_spec: str, project_root: Path) -> bool:
    catalog = ExtensionCatalog(project_root)
    if catalog.get_extension_info(ext_spec):
        return True
    return any(
        str(ext.get("name", "")).lower() == ext_spec.lower()
        for ext in catalog.search()
    )

try:
    _install_extension_during_init(project_path, ext_spec, version)
except ValueError as exc:
    if "not found in bundled extensions or catalog" in str(exc):
        suggest_available_extension_ids()
    else:
        raise

When it happens

Trigger: `specify init --extension <value>` where value is a typo, wrong-case id, display name with no exact catalog match, or an extension that exists only in a catalog that is not configured.

Common situations: Using a display name instead of the exact id, adding a community extension not present in the default installable catalog, a stale cache, or a custom catalog that does not include the entry.

Related errors

• Could not query extension catalog: {catalog_error}
• Extension '{ext_spec}' is in the '{catalog_name}' catalog bu
• {exc}
• Directory not found: {source_path}
• No extension.yml found in {source_path}

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