github/spec-kit · error · BundlerError

Bundle '{bundle_id}' resolves only from a discovery-only sou

Error message

Bundle '{bundle_id}' resolves only from a discovery-only source ('{resolved.source.id}'); it cannot be installed from there.

What it means

During bundle install, the bundle id resolved through the catalog stack to a source whose install_allowed is False (a discovery-only source, e.g. a search/index registry). Discovery-only sources can tell you a bundle exists but are not permitted installation origins, so the CLI refuses before downloading a manifest. Mirrors the FR-025 rule enforced on update.

Source

Thrown at src/specify_cli/commands/bundle/__init__.py:383

        from ...bundler.services.adapters import DefaultPrimitiveInstaller
        from ...bundler.services.installer import install_bundle
        from ...bundler.services.resolver import resolve_install_plan

        project_root = find_project_root()

        local_manifest = _local_manifest_source(bundle_id)
        if local_manifest is not None:
            manifest = local_manifest
            _validate_manifest_structure(
                manifest,
                source=f"Local bundle source {bundle_id!r}",
            )
        else:
            stack = _build_stack(project_root or Path.cwd(), offline=offline)
            resolved = stack.resolve(bundle_id)

            if not resolved.install_allowed:
                raise BundlerError(
                    f"Bundle '{bundle_id}' resolves only from a discovery-only source "
                    f"('{resolved.source.id}'); it cannot be installed from there."
                )
            manifest = _download_manifest(resolved, offline=offline)

        if project_root is None:
            init_integration = _resolve_init_integration(integration, manifest)
            # Resolve all hard compatibility gates before ``specify init``.
            # Otherwise an incompatible but structurally valid bundle would
            # initialize a project and only then fail its version/integration
            # checks, leaving state behind after a failed install.
            resolve_install_plan(
                manifest,
                speckit_version=_speckit_version(),
                active_integration=init_integration,
                integration_explicit=True,
            )
            console.print(

View on GitHub (pinned to bf88c9f9a8)

Solutions

Find the bundle's real install source (its published repo/URL) and install from a path: specify bundle install ./bundle.yml, a bundle directory, or a .zip artifact.
Configure the catalog stack so the bundle is resolvable from an install-allowed source.
If you operate the discovery source, add a download_url and mark it install-allowed.

Example fix

# before
specify bundle install some-indexed-bundle

# after — install from the actual artifact
specify bundle install ./some-indexed-bundle.zip

Defensive patterns

Strategy: validation

Validate before calling

stack = _build_stack(project_root, offline=offline)
resolved = stack.resolve(bundle_id)
if not resolved.install_allowed:
    raise SystemExit(
        f"{bundle_id} is discovery-only on '{resolved.source.id}'; "
        "install from an artifact path instead"
    )

Type guard

def is_installable(resolved) -> bool:
    """True when the resolved source permits installation."""
    return resolved.install_allowed

Try / catch

try:
    bundle_install(...)
except BundlerError as exc:
    if "discovery-only source" in str(exc):
        # fall back to a local artifact path install
        ...

Prevention

Check resolved.install_allowed after stack.resolve() before attempting install.
Keep a local copy (.zip / directory) of bundles you rely on.
Know which of your configured catalog sources are install-allowed.

When it happens

Trigger: specify bundle install <id> (or the API path: _build_stack(...).resolve(id) then checking resolved.install_allowed) where the id is only present in a source registered with install_allowed=False and no local ./bundle.yml or path argument was given.

Common situations: A global search catalog that indexes bundles hosted elsewhere; corporate registries split into 'browse' and 'install' mirrors; the install-enabled source is offline/unreachable so resolution fell through to the discovery-only one.

Related errors

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