{"record":{"id":"7041e36682c14760","repo":"OpenBMB/ChatDev","slug":"document-root-not-mapping","errorCode":"document_root_not_mapping","errorMessage":"document_root_not_mapping","messagePattern":"document_root_not_mapping","errorType":"http","errorClass":"HTTPException","httpStatus":422,"severity":"error","filePath":"server/config_schema_router.py","lineNumber":53,"sourceCode":"\n\n@router.post(\"/schema\")\ndef get_schema(request: SchemaRequest) -> Dict[str, Any]:\n    try:\n        return build_schema_response(request.breadcrumbs)\n    except SchemaResolutionError as exc:\n        raise HTTPException(status_code=422, detail={\"message\": str(exc)}) from exc\n\n\n@router.post(\"/schema/validate\")\ndef validate_document(request: SchemaValidateRequest) -> Dict[str, Any]:\n    try:\n        parsed = yaml.safe_load(request.document)\n    except yaml.YAMLError as exc:\n        raise HTTPException(status_code=400, detail={\"message\": \"invalid_yaml\", \"error\": str(exc)}) from exc\n\n    if not isinstance(parsed, Mapping):\n        raise HTTPException(status_code=422, detail={\"message\": \"document_root_not_mapping\"})\n\n    try:\n        load_design_from_mapping(parsed)\n    except ConfigError as exc:\n        return {\n            \"valid\": False,\n            \"error\": str(exc),\n            \"path\": exc.path,\n            \"schema\": _resolve_schema(request.breadcrumbs),\n        }\n\n    return {\n        \"valid\": True,\n        \"schema\": _resolve_schema(request.breadcrumbs),\n    }\n\n\n__all__ = [\"router\"]","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/OpenBMB/ChatDev/blob/4fb2db0ea90375ce1059f44fe03ffbd191a7a169/server/config_schema_router.py#L35-L71","documentation":"The YAML parsed successfully but the resulting value is not a mapping (dict). The schema loader expects the document root to be a mapping so load_design_from_mapping can process it. A bare scalar, list, or null root triggers this 422.","triggerScenarios":"POST /schema/validate where the document root is a list (e.g. starts with '- '), a plain string, a number, or empty/null content (yaml.safe_load returns None for empty input).","commonSituations":"Submitting a YAML array of documents instead of a keyed config, submitting an empty string, wrapping the config under the wrong structure so the top level is a scalar.","solutions":["Ensure the top-level YAML structure uses key: value pairs","If the document is a list, wrap it in a mapping (e.g. designs: [...])","For empty documents, add at least a top-level key such as an empty mapping {}","Check that you didn't paste a fragment that begins with a list item"],"exampleFix":"# before\n- task: a\n- task: b\n# after\ndesign:\n  - task: a\n  - task: b","handlingStrategy":"validation","validationCode":"import yaml\nfrom collections.abc import Mapping\ndef root_is_mapping(doc: str) -> bool:\n    parsed = yaml.safe_load(doc)\n    return isinstance(parsed, Mapping)","typeGuard":"from collections.abc import Mapping\ndef is_mapping_root(parsed) -> bool:\n    return isinstance(parsed, Mapping)","tryCatchPattern":"if resp.status_code == 422 and resp.json()['detail']['message'] == 'document_root_not_mapping':\n    # restructure document root as key: value pairs\n    ...","preventionTips":["Always start config documents with a top-level key","Treat empty documents as {} explicitly"],"tags":["yaml","schema-validation","http-422"],"backgroundTag":"schema-validation-failed","analyzedSha":"4fb2db0ea90375ce1059f44fe03ffbd191a7a169","analyzedAt":"2026-08-27T14:35:29.622Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}