github/spec-kit · error · BundlerError

Downloaded bundle version mismatch for {entry.id!r}: catalog

Error message

Downloaded bundle version mismatch for {entry.id!r}: catalog declares {entry.version!r}, but the manifest declares {manifest.bundle.version!r}.

What it means

After confirming the bundle id, Spec Kit requires the catalog entry version and downloaded manifest version to match exactly. A difference means the catalog metadata and published artifact describe different releases, so installation/update is stopped before mutation.

Source

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

    report = validate_manifest(manifest)
    if report.ok:
        return
    raise BundlerError(
        f"{source} contains an invalid bundle manifest:\n  - "
        + "\n  - ".join(report.errors)
    )


def _validate_catalog_manifest(entry, manifest) -> None:
    """Bind a downloaded manifest to the catalog identity that selected it."""
    if manifest.bundle.id != entry.id:
        raise BundlerError(
            f"Downloaded bundle id mismatch: catalog entry {entry.id!r} points to "
            f"a manifest for {manifest.bundle.id!r}."
        )
    if manifest.bundle.version != entry.version:
        raise BundlerError(
            f"Downloaded bundle version mismatch for {entry.id!r}: catalog declares "
            f"{entry.version!r}, but the manifest declares "
            f"{manifest.bundle.version!r}."
        )
    _validate_manifest_structure(
        manifest,
        source=f"Downloaded bundle {entry.id!r}",
    )


def register(app: typer.Typer) -> None:
    """Attach the bundle command group to the root Typer app."""
    app.add_typer(bundle_app, name="bundle")

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Make the catalog entry version exactly equal to bundle.yml's bundle.version, normally plain semver without a `v` prefix.
2. If the catalog version is new, ensure download_url points to the newly published artifact.
3. Re-tag/re-publish the release if the artifact itself carries the stale version.
4. Retry `specify bundle info <id>` to verify the aligned pair before installing.

Example fix

# catalog.json (before)
{"id": "demo", "version": "1.1.0"}
# bundle.yml
version: 1.0.0

# catalog.json (after)
{"id": "demo", "version": "1.0.0"}

def catalog_and_manifest_versions_match(entry, manifest) -> bool:
    return manifest.bundle.version == entry.version

except BundlerError as exc:
    if "bundle version mismatch" in str(exc):
        block_install_until_catalog_and_artifact_are_aligned()
    else:
        raise

When it happens

Trigger: `_validate_catalog_manifest` compares `manifest.bundle.version` with `entry.version` after a catalog download and finds they differ, including formatting differences such as `v1.2.3` versus `1.2.3`.

Common situations: The artifact version was bumped but the catalog still lists the old version, the catalog was bumped while the download URL still points to the old tag, or one side added a `v` prefix.

Related errors

• Downloaded bundle id mismatch: catalog entry {entry.id!r} po
• Refusing to download {label}: URL is malformed: {url}
• Refusing to download {label} over non-HTTPS URL: {url}
• Refusing to download {label} from URL with no host: {url}
• Failed to download bundle '{entry_id}' from {_source_desc}:

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