github/spec-kit · error · BundlerError

Bundle '{manifest.bundle.id}' targets integration '{required

Error message

Bundle '{manifest.bundle.id}' targets integration '{required}', but this project's active integration could not be determined (missing or unreadable .specify/integration.json). Re-run with '--integration' to confirm the target, or repair the project before installing.

What it means

The second FR-019 branch: the bundle pins an integration but the project's active integration is None — .specify/integration.json is missing or unreadable — and the caller did not pass an explicit --integration (integration_explicit is False). Rather than silently adopting the bundle's required integration, resolution fails and asks for an explicit confirmation.

Source

Thrown at src/specify_cli/bundler/services/resolver.py:100

    # integration id but satisfied NEITHER guard below (the first is a truthiness
    # test, the second an ``is None`` test), so a pinned bundle was silently
    # adopted: precisely the outcome this guard exists to prevent. Treat blank as
    # indeterminate, and strip first like the writer
    # (``integration_state.clean_integration_key``) so a padded value is not
    # reported as clashing with itself.
    if active_integration is not None:
        active_integration = active_integration.strip() or None
    effective_integration = active_integration
    if manifest.integration is not None:
        required = manifest.integration.id
        if active_integration and required != active_integration:
            raise BundlerError(
                f"Bundle '{manifest.bundle.id}' targets integration '{required}', "
                f"but this project's active integration is '{active_integration}'. "
                "Installing it would conflict; aborting with no changes."
            )
        if active_integration is None and not integration_explicit:
            raise BundlerError(
                f"Bundle '{manifest.bundle.id}' targets integration '{required}', "
                "but this project's active integration could not be determined "
                "(missing or unreadable .specify/integration.json). Re-run with "
                "'--integration' to confirm the target, or repair the project "
                "before installing."
            )
        effective_integration = required

    warnings: list[str] = []
    if manifest.requires.tools:
        warnings.append(
            "Requires external tools: " + ", ".join(manifest.requires.tools)
        )
    if manifest.requires.mcp:
        warnings.append("Requires MCP servers: " + ", ".join(manifest.requires.mcp))

    return InstallPlan(
        bundle_id=manifest.bundle.id,

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Re-run with an explicit target: specify bundle install <id> --integration <integration-id>.
2. Repair the project state: re-run specify init (or recreate .specify/integration.json) so active_integration is detectable, then retry without the flag.
3. If the integration.json exists but is corrupt JSON, fix or delete-and-reinit so detection works.

Example fix

# before
specify bundle install my-bundle

# after
specify bundle install my-bundle --integration claude

from specify_cli.bundler.services.integration_state import active_integration

detected = active_integration(project_root)
if detected is None and manifest.integration is not None:
    integration = input("Active integration unknown; pass --integration explicitly") or abort

def needs_explicit_integration(manifest, active: str | None) -> bool:
    """True when resolution will demand an explicit --integration."""
    return manifest.integration is not None and active is None

try:
    resolve_install_plan(manifest, active_integration=detected, integration_explicit=False, ...)
except BundlerError as exc:
    if "could not be determined" in str(exc):
        # retry with explicit override: specify bundle install <id> --integration claude
        ...

When it happens

Trigger: resolve_install_plan(manifest, active_integration=None, integration_explicit=False) when manifest.integration is not None; via 'specify bundle install <pinned-bundle>' in a directory where .specify/integration.json was deleted, corrupted, or never created.

Common situations: Installing into a manually-created .specify directory instead of one produced by specify init; a partially-deleted project; CI runs that strip state files; .specify/integration.json containing an unreadable/invalid payload.

Related errors

• Bundle '{manifest.bundle.id}' targets integration '{required
• 'integration' must be a mapping when present.
• Failed to initialize a Spec Kit project (integration '{integ
• Malformed catalog config at {path}: expected a mapping at th
• Unsupported catalog config schema version '{str(schema_versi

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