{"record":{"id":"5719191250bc8582","repo":"github/spec-kit","slug":"failed-to-initialize-a-spec-kit-project-integrati","errorCode":null,"errorMessage":"Failed to initialize a Spec Kit project (integration '{integration}').","messagePattern":"Failed to initialize a Spec Kit project \\(integration '(.+?)'\\)\\.","errorType":"exception","errorClass":"BundlerError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/commands/bundle/__init__.py","lineNumber":132,"sourceCode":"        init_cb(\n            project_name=None,\n            script_type=script_type,\n            ignore_agent_tools=True,\n            here=True,\n            force=True,\n            skip_tls=False,\n            debug=False,\n            github_token=None,\n            offline=offline,\n            preset=None,\n            integration=integration,\n            integration_options=None,\n            extensions=None,\n            trust_extension_urls=False,\n        )\n    except typer.Exit as exc:\n        if exc.exit_code:\n            raise BundlerError(\n                f\"Failed to initialize a Spec Kit project (integration '{integration}').\"\n            ) from exc\n\n\ndef _resolve_init_integration(override: str | None, manifest) -> str:\n    \"\"\"Precedence (FR-013): explicit override → bundle-declared → default.\"\"\"\n    from ..._agent_config import resolve_default_init_integration\n\n    if override:\n        return override\n    if manifest is not None and manifest.integration is not None:\n        return manifest.integration.id\n    return resolve_default_init_integration()\n\n\n# ===== Consume =====\n\n","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/commands/bundle/__init__.py#L114-L150","documentation":"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.).","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nspecify bundle install my-bundle   # bundle pins integration: cursor-agent, CLI absent\n\n# after (after installing the CLI, or override)\nnpm install -g cursor-agent\nspecify bundle install my-bundle","handlingStrategy":"try-catch","validationCode":"import shutil\nfrom specify_cli.integrations import INTEGRATION_REGISTRY\n\nintegration = resolved_integration_id  # from _resolve_init_integration precedence\nif integration not in INTEGRATION_REGISTRY:\n    raise SystemExit(f\"Unknown integration: {integration}\")\nif not shutil.which(integration):\n    raise SystemExit(f\"CLI for '{integration}' not installed\")","typeGuard":null,"tryCatchPattern":"try:\n    bundle_install(...)\nexcept BundlerError as exc:\n    if \"Failed to initialize a Spec Kit project\" in str(exc):\n        # inspect exc.__cause__ (typer.Exit) and stderr above; verify integration id + CLI\\n        ...","preventionTips":["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."],"tags":["bundler","init","integration","cli"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}