github/spec-kit · error · BundlerError

Manifest is missing the required 'bundle' mapping.

Error message

Manifest is missing the required 'bundle' mapping.

What it means

Raised by BundleManifest.from_dict when the top-level mapping lacks a valid 'bundle' key — the required mapping holding id, name, version, role, description, author, and license. A missing 'bundle', or a present-but-non-mapping value (e.g. a bare string), both raise, because BundleMeta cannot be constructed without it.

Source

Thrown at src/specify_cli/bundler/models/manifest.py:103

    # -- construction ---------------------------------------------------------

    @classmethod
    def from_file(cls, path: Path) -> "BundleManifest":
        data = load_yaml(path)
        manifest = cls.from_dict(data)
        manifest.source_path = Path(path)
        return manifest

    @classmethod
    def from_dict(cls, data: Any) -> "BundleManifest":
        if not isinstance(data, dict):
            raise BundlerError("Manifest must be a YAML mapping at the top level.")

        schema_version = _text(data.get("schema_version"))

        bundle_raw = data.get("bundle")
        if not isinstance(bundle_raw, dict):
            raise BundlerError("Manifest is missing the required 'bundle' mapping.")
        meta = BundleMeta(
            id=_text(bundle_raw.get("id")),
            name=_text(bundle_raw.get("name")),
            version=_text(bundle_raw.get("version")),
            role=_text(bundle_raw.get("role")),
            description=_text(bundle_raw.get("description")),
            author=_text(bundle_raw.get("author")),
            license=_text(bundle_raw.get("license")),
        )

        requires_raw = data.get("requires")
        if requires_raw is None:
            requires_raw = {}
        elif not isinstance(requires_raw, dict):
            raise BundlerError("'requires' must be a mapping when present.")
        requires = Requires(
            speckit_version=_text(requires_raw.get("speckit_version")),
            tools=_parse_str_list(requires_raw.get("tools"), "requires.tools"),

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Add a 'bundle:' mapping with at least id/name/version.
2. Move misplaced top-level metadata keys (id, name, version, role, ...) under 'bundle:'.
3. Compare against a manifest produced by 'specify bundle create' for the exact shape.

Example fix

# before (bundle.yml)
schema_version: 1
id: my-bundle
name: My Bundle
version: 1.0.0

# after
schema_version: 1
bundle:
  id: my-bundle
  name: My Bundle
  version: 1.0.0

import yaml

def manifest_has_bundle_mapping(data: dict) -> bool:
    return isinstance(data.get("bundle"), dict)

def has_bundle_mapping(data: object) -> bool:
    return isinstance(data, dict) and isinstance(data.get("bundle"), dict)

try:
    manifest = BundleManifest.from_file(p)
except BundlerError as e:
    if "'bundle' mapping" in str(e):
        # reject the bundle in listing / fail install with a clear message
        ...

When it happens

Trigger: BundleManifest.from_file/from_file is called on a manifest whose top-level mapping has no 'bundle:' key, or where 'bundle:' is a scalar/list (e.g. 'bundle: my-bundle').

Common situations: Authoring a manifest and inlining bundle metadata at the top level instead of nesting it under 'bundle:'; renaming the key (e.g. 'metadata:'); a partially generated manifest.

Related errors

• Manifest must be a YAML mapping at the top level.
• 'requires' must be a mapping when present.
• 'integration' must be a mapping when present.
• 'provides' must be a mapping when present.
• '{field_name}' must be a list of strings when present.

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