{"record":{"id":"2dbe279f9ab3b71c","repo":"github/spec-kit","slug":"descriptor-root-must-be-a-yaml-mapping-got-type","errorCode":null,"errorMessage":"Descriptor root must be a YAML mapping, got {type(self.data).__name__}","messagePattern":"Descriptor root must be a YAML mapping, got (.+?)","errorType":"validation","errorClass":"IntegrationDescriptorError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/integrations/catalog.py","lineNumber":692,"sourceCode":"    @staticmethod\n    def _load(path: Path) -> dict:\n        try:\n            with open(path, \"r\", encoding=\"utf-8\") as fh:\n                return yaml.safe_load(fh) or {}\n        except yaml.YAMLError as exc:\n            raise IntegrationDescriptorError(f\"Invalid YAML in {path}: {exc}\")\n        except FileNotFoundError:\n            raise IntegrationDescriptorError(f\"Descriptor not found: {path}\")\n        except (OSError, UnicodeError) as exc:\n            raise IntegrationDescriptorError(\n                f\"Unable to read descriptor {path}: {exc}\"\n            )\n\n    # -- Validation -------------------------------------------------------\n\n    def _validate(self) -> None:\n        if not isinstance(self.data, dict):\n            raise IntegrationDescriptorError(\n                f\"Descriptor root must be a YAML mapping, got {type(self.data).__name__}\"\n            )\n        for field in self.REQUIRED_TOP_LEVEL:\n            if field not in self.data:\n                raise IntegrationDescriptorError(\n                    f\"Missing required field: {field}\"\n                )\n\n        if self.data[\"schema_version\"] != self.SCHEMA_VERSION:\n            raise IntegrationDescriptorError(\n                f\"Unsupported schema version: {self.data['schema_version']} \"\n                f\"(expected {self.SCHEMA_VERSION})\"\n            )\n\n        integ = self.data[\"integration\"]\n        if not isinstance(integ, dict):\n            raise IntegrationDescriptorError(\n                \"'integration' must be a mapping\"","sourceCodeStart":674,"sourceCodeEnd":710,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/integrations/catalog.py#L674-L710","documentation":"Error \"Descriptor root must be a YAML mapping, got {type(self.data).__name__}\" thrown in github/spec-kit.","triggerScenarios":"Thrown at src/specify_cli/integrations/catalog.py:692 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Make the descriptor's top level a YAML mapping."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}