github/spec-kit · error · BundlerError

{source} contains an invalid bundle manifest:\n - " + "\n

Error message

{source} contains an invalid bundle manifest:\n  - " + "\n  - ".join(report.errors)

What it means

Before any project mutation, Spec Kit runs the structural manifest validator and rejects a bundle whose manifest has errors. The message lists every failure, such as an unsupported schema_version, missing required fields, invalid semver, unsafe bundle id, unpinned component versions, invalid preset strategy/priority, or an invalid requires.speckit_version constraint.

Source

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

        raise BundlerError(
            f"Downloaded content for bundle '{entry_id}' from {_source_desc} "
            f"is not valid YAML: {exc}"
        ) from exc
    except Exception as exc:  # noqa: BLE001
        raise BundlerError(
            f"Failed to parse downloaded bundle '{entry_id}' from "
            f"{_source_desc}: {exc}"
        ) from exc


def _validate_manifest_structure(manifest, *, source: str) -> None:
    """Reject a malformed manifest before any project mutation can occur."""
    from ...bundler.services.validator import validate_manifest

    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}."
        )

View on GitHub (pinned to bf88c9f9a8)

Solutions

Read each bullet in the error; every line names one concrete manifest defect.
Set `schema_version: "1.0"` and populate every required bundle field: id, name, version, role, description, author, license.
Use a valid semver bundle.version, a slug-safe lowercase bundle.id, and pinned semver versions for extension/preset/workflow components.
Give presets an integer priority and a supported strategy, and use a valid Spec Kit version constraint in requires.speckit_version.
Run `specify bundle validate` on the corrected source, then rebuild/upload ZIP artifacts and update the catalog.

Example fix

# bundle.yml (before)
schema_version: "1.0"
bundle:
  id: demo
  name: Demo
  version: 1.0

# bundle.yml (after)
schema_version: "1.0"
bundle:
  id: demo
  name: Demo
  version: 1.0.0
  role: preset-pack
  description: Demo bundle
  author: Example Team
  license: MIT
requires:
  speckit_version: ">=0.20.0"

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
from specify_cli.bundler.models.manifest import BundleManifest
from specify_cli.bundler.services.validator import validate_manifest

def manifest_is_structurally_valid(path: Path) -> bool:
    try:
        report = validate_manifest(BundleManifest.from_file(path))
    except Exception:
        return False
    return report.ok

Try / catch

except BundlerError as exc:
    if "invalid bundle manifest" in str(exc):
        show_each_bullet_and_block_install()
    else:
        raise

Prevention

Run `specify bundle validate` in the bundle's CI job.
Treat required-field and semver checks as release gates, not warnings.
Regenerate and retest ZIP artifacts whenever bundle.yml changes.

When it happens

Trigger: Installing or inspecting a catalog bundle after _validate_catalog_manifest, or installing a local bundle path, when validate_manifest returns a non-empty report. Local sources use `Local bundle source '<path>'`; catalog downloads use `Downloaded bundle '<id>'`.

Common situations: A hand-edited bundle.yml omits author/license/requires.speckit_version, uses schema_version 2.0 while this version supports 1.0, leaves extension versions unpinned, or changes a preset strategy to an unsupported value.

Related errors

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