{"record":{"id":"697b97b726d3ea1f","repo":"github/spec-kit","slug":"manifest-is-missing-the-required-bundle-mapping","errorCode":null,"errorMessage":"Manifest is missing the required 'bundle' mapping.","messagePattern":"Manifest is missing the required 'bundle' mapping\\.","errorType":"exception","errorClass":"BundlerError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/bundler/models/manifest.py","lineNumber":103,"sourceCode":"    # -- construction ---------------------------------------------------------\n\n    @classmethod\n    def from_file(cls, path: Path) -> \"BundleManifest\":\n        data = load_yaml(path)\n        manifest = cls.from_dict(data)\n        manifest.source_path = Path(path)\n        return manifest\n\n    @classmethod\n    def from_dict(cls, data: Any) -> \"BundleManifest\":\n        if not isinstance(data, dict):\n            raise BundlerError(\"Manifest must be a YAML mapping at the top level.\")\n\n        schema_version = _text(data.get(\"schema_version\"))\n\n        bundle_raw = data.get(\"bundle\")\n        if not isinstance(bundle_raw, dict):\n            raise BundlerError(\"Manifest is missing the required 'bundle' mapping.\")\n        meta = BundleMeta(\n            id=_text(bundle_raw.get(\"id\")),\n            name=_text(bundle_raw.get(\"name\")),\n            version=_text(bundle_raw.get(\"version\")),\n            role=_text(bundle_raw.get(\"role\")),\n            description=_text(bundle_raw.get(\"description\")),\n            author=_text(bundle_raw.get(\"author\")),\n            license=_text(bundle_raw.get(\"license\")),\n        )\n\n        requires_raw = data.get(\"requires\")\n        if requires_raw is None:\n            requires_raw = {}\n        elif not isinstance(requires_raw, dict):\n            raise BundlerError(\"'requires' must be a mapping when present.\")\n        requires = Requires(\n            speckit_version=_text(requires_raw.get(\"speckit_version\")),\n            tools=_parse_str_list(requires_raw.get(\"tools\"), \"requires.tools\"),","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/bundler/models/manifest.py#L85-L121","documentation":"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.","triggerScenarios":"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').","commonSituations":"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.","solutions":["Add a 'bundle:' mapping with at least id/name/version.","Move misplaced top-level metadata keys (id, name, version, role, ...) under 'bundle:'.","Compare against a manifest produced by 'specify bundle create' for the exact shape."],"exampleFix":"# before (bundle.yml)\nschema_version: 1\nid: my-bundle\nname: My Bundle\nversion: 1.0.0\n\n# after\nschema_version: 1\nbundle:\n  id: my-bundle\n  name: My Bundle\n  version: 1.0.0","handlingStrategy":"validation","validationCode":"import yaml\n\ndef manifest_has_bundle_mapping(data: dict) -> bool:\n    return isinstance(data.get(\"bundle\"), dict)","typeGuard":"def has_bundle_mapping(data: object) -> bool:\n    return isinstance(data, dict) and isinstance(data.get(\"bundle\"), dict)","tryCatchPattern":"try:\n    manifest = BundleManifest.from_file(p)\nexcept BundlerError as e:\n    if \"'bundle' mapping\" in str(e):\n        # reject the bundle in listing / fail install with a clear message\n        ...","preventionTips":["All bundle identity fields live under 'bundle:', never at the top level.","Copy a known-good manifest as the starting template.","Assert 'bundle' in the mapping in pre-publish checks."],"tags":["bundler","manifest","yaml","validation"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}