github/spec-kit · error · BundlerError

Failed to initialize a Spec Kit project (integration '{integ

Error message

Failed to initialize a Spec Kit project (integration '{integration}').

What it means

During bundle install into a non-project directory, the CLI shells out to the specify init flow with the resolved integration; if that inner flow signals failure via typer.Exit with a non-zero exit_code, this BundlerError wraps it so bundle_install()'s except BundlerError handler reports a clean message instead of a traceback. The root cause is whatever made init fail (invalid integration id, template errors, etc.).

Source

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

        init_cb(
            project_name=None,
            script_type=script_type,
            ignore_agent_tools=True,
            here=True,
            force=True,
            skip_tls=False,
            debug=False,
            github_token=None,
            offline=offline,
            preset=None,
            integration=integration,
            integration_options=None,
            extensions=None,
            trust_extension_urls=False,
        )
    except typer.Exit as exc:
        if exc.exit_code:
            raise BundlerError(
                f"Failed to initialize a Spec Kit project (integration '{integration}')."
            ) from exc


def _resolve_init_integration(override: str | None, manifest) -> str:
    """Precedence (FR-013): explicit override → bundle-declared → default."""
    from ..._agent_config import resolve_default_init_integration

    if override:
        return override
    if manifest is not None and manifest.integration is not None:
        return manifest.integration.id
    return resolve_default_init_integration()


# ===== Consume =====

View on GitHub (pinned to bf88c9f9a8)

Solutions

Re-run with an explicit valid integration: specify bundle install <bundle> --integration <known-key> (list valid keys via specify init --help or the integration registry).
Install the target agent's CLI first (e.g. npm install -g <agent-cli>) so the init CLI check passes.
Run specify init manually in a scratch dir with the same integration to surface the underlying init error, fix that, then retry the bundle install.
Check the chained exception (__cause__) in code: exc.__cause__.exit_code and the init output above the error.

Example fix

# before
specify bundle install my-bundle   # bundle pins integration: cursor-agent, CLI absent

# after (after installing the CLI, or override)
npm install -g cursor-agent
specify bundle install my-bundle

Defensive patterns

Strategy: try-catch

Validate before calling

import shutil
from specify_cli.integrations import INTEGRATION_REGISTRY

integration = resolved_integration_id  # from _resolve_init_integration precedence
if integration not in INTEGRATION_REGISTRY:
    raise SystemExit(f"Unknown integration: {integration}")
if not shutil.which(integration):
    raise SystemExit(f"CLI for '{integration}' not installed")

Try / catch

try:
    bundle_install(...)
except BundlerError as exc:
    if "Failed to initialize a Spec Kit project" in str(exc):
        # inspect exc.__cause__ (typer.Exit) and stderr above; verify integration id + CLI\n        ...

Prevention

Run 'specify init' once in a scratch dir with the target integration to verify it works.
Install the target agent CLI before installing bundles that pin it.
Prefer installing bundles into already-initialized projects to skip the init path.

When it happens

Trigger: specify bundle install <bundle> run outside an initialized project, where the bundled _run_init(...) raises typer.Exit(1) — e.g. the resolved integration id (from _resolve_init_integration precedence: --integration override → manifest.integration.id → default) is not registered or its CLI tool is missing.

Common situations: A bundle pinned to an integration whose executable is not installed (shutil.which fails); an invalid --integration value; network/extension failures during init; using a fork whose integration registry lacks the bundle's pinned agent.

Related errors

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