{"record":{"id":"2282d28802693ec7","repo":"OpenBMB/ChatDev","slug":"yaml-root-must-be-a-mapping-2282d2","errorCode":null,"errorMessage":"YAML root must be a mapping","messagePattern":"YAML root must be a mapping","errorType":"validation","errorClass":"ConfigError","httpStatus":null,"severity":"error","filePath":"check/check_yaml.py","lineNumber":21,"sourceCode":"import argparse\nfrom pathlib import Path\nfrom typing import Any, List, Optional\n\nfrom entity.configs import ConfigError, DesignConfig\nfrom utils.io_utils import read_yaml\n\n\ndef validate_design(data: Any, set_defaults: bool = True, fn_module_ref: Optional[str] = None) -> List[str]:\n    \"\"\"Validate raw YAML data using the typed config loader.\n    \n    Note: This function validates schema structure only, without resolving\n    environment variable placeholders like ${VAR}. This allows workflows to\n    be saved even when environment variables are not yet configured - they\n    will be resolved at runtime.\n    \"\"\"\n    try:\n        if not isinstance(data, dict):\n            raise ConfigError(\"YAML root must be a mapping\", path=\"root\")\n        # Use DesignConfig.from_dict directly to skip placeholder resolution\n        # Users may configure environment variables at runtime\n        DesignConfig.from_dict(data)\n        return []\n    except ConfigError as exc:\n        return [str(exc)]\n\n\ndef main() -> None:\n    parser = argparse.ArgumentParser(description=\"Validate workflow YAML structure against the typed config loader\")\n    parser.add_argument(\"path\", help=\"Path to the workflow YAML file\")\n    args = parser.parse_args()\n\n    data = read_yaml(args.path)\n    errors = validate_design(data)\n    if errors:\n        print(\"Design validation failed:\")\n        for err in errors:","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/OpenBMB/ChatDev/blob/4fb2db0ea90375ce1059f44fe03ffbd191a7a169/check/check_yaml.py#L3-L39","documentation":"Wrapped as WorkflowExecutionError when persist_workflow throws an unexpected exception during upload or update. The message interpolates the action ('upload'/'update') and original exception; HTTPException and ValidationError are re-raised untouched, so only genuine internal failures hit this path.","triggerScenarios":"Disk/permission errors while writing YAML, failures in the persist pipeline, or bugs in workflow serialization during upload or update calls.","commonSituations":"Read-only YAML_DIR in containers; disk full; concurrent writes; schema surprises that pass validation but break persistence.","solutions":["Read the server log entry 'Unexpected error during workflow {action}' for the original traceback.","Fix the underlying cause (permissions, disk, path config) in YAML_DIR.","Retry the operation once the environment is corrected."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"catch (WorkflowExecutionError e) { log.error(e.message); retryOnceAfterEnvFix(); }","preventionTips":["Writable YAML_DIR with adequate disk","Watch server log_exception entries for root cause"],"tags":["workflow","internal-error","yaml"],"backgroundTag":"workflow-persist-failed","analyzedSha":"4fb2db0ea90375ce1059f44fe03ffbd191a7a169","analyzedAt":"2026-08-27T14:35:29.622Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}