github/spec-kit · error · BundlerError

Bundle '{manifest.bundle.id}' requires Spec Kit {manifest.re

Error message

Bundle '{manifest.bundle.id}' requires Spec Kit {manifest.requires.speckit_version}, but this project uses {speckit_version}. Update Spec Kit or choose a compatible bundle.

What it means

The FR-016 Spec Kit version gate in resolve_install_plan(): the manifest declares requires.speckit_version, and the project's Spec Kit version does not satisfy that constraint (via satisfies()). This is a hard gate — the bundle refuses to install against an incompatible Spec Kit rather than half-working. Only enforced when the enforce_version argument is true and requires.speckit_version is non-empty.

Source

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

    integration clash). Soft issues are collected in ``plan.warnings``.

    *integration_explicit* signals that ``active_integration`` came from an
    explicit ``--integration`` override rather than project auto-detection. When
    a bundle pins an integration but the project's active integration cannot be
    determined (``active_integration is None``) and the caller did not supply an
    explicit override, resolution fails instead of silently adopting the
    bundle's required integration (FR-019 guard).
    """
    structural = manifest.structural_errors()
    if structural:
        raise BundlerError(
            "Cannot resolve an invalid manifest:\n  - " + "\n  - ".join(structural)
        )

    # FR-016: SpecKit version gate — refuse incompatible installs.
    if enforce_version and manifest.requires.speckit_version:
        if not satisfies(speckit_version, manifest.requires.speckit_version):
            raise BundlerError(
                f"Bundle '{manifest.bundle.id}' requires Spec Kit "
                f"{manifest.requires.speckit_version}, but this project uses "
                f"{speckit_version}. Update Spec Kit or choose a compatible bundle."
            )

    # FR-019: integration-compatibility — a bundle that pins a different
    # integration than the project's active one halts (no silent change).
    #
    # A blank integration arrives as ``""``, not ``None`` — which is not a usable
    # 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

View on GitHub (pinned to bf88c9f9a8)

Solutions

  1. Update Spec Kit so the project version satisfies the constraint: pip install -U specify-cli (or the project's package manager equivalent), then retry the install.
  2. Pick a bundle version whose requires.speckit_version matches your installed Spec Kit.
  3. If you own the bundle, relax/correct requires.speckit_version in bundle.yml (e.g. '>=1.2' instead of '>=2.0').
  4. Programmatically: pre-check satisfies(speckit_version, manifest.requires.speckit_version) and skip with a warning instead of raising.

Example fix

# before (bundle.yml)
requires:
  speckit_version: ">=2.0"

# after (if the bundle actually works on 1.4+)
requires:
  speckit_version: ">=1.4"
Defensive patterns

Strategy: validation

Validate before calling

from specify_cli.bundler.services.resolver import resolve_install_plan  # satisfies lives nearby
from specify_cli.bundler.compatability import satisfies  # adjust import to project layout

constraint = manifest.requires.speckit_version
if constraint and not satisfies(speckit_version, constraint):
    print(f"Skip {manifest.bundle.id}: needs Spec Kit {constraint}, have {speckit_version}")

Type guard

def bundle_matches_speckit(manifest, speckit_version: str) -> bool:
    c = manifest.requires.speckit_version
    return not c or satisfies(speckit_version, c)

Try / catch

try:
    resolve_install_plan(manifest, speckit_version=ver, ...)
except BundlerError as exc:
    if "requires Spec Kit" in str(exc):
        # skip bundle or prompt user to upgrade Spec Kit
        ...

Prevention

When it happens

Trigger: resolve_install_plan(manifest, speckit_version='1.4.0', ...) with a bundle.yml whose requires.speckit_version is '>=2.0' (or requires '1.x' while running 2.x); reached through 'specify bundle install <id-or-path>' in a project with an older/newer specify CLI.

Common situations: A bundle published for a newer Spec Kit release installed by a user on an older pip package; or after a Spec Kit major upgrade, older pinned bundles no longer satisfy their own constraint.

Related errors

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