OpenBMB/ChatDev · error · ConfigError

YAML root must be a mapping

Error message

YAML root must be a mapping

What it means

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.

Source

Thrown at check/check_yaml.py:21

import argparse
from pathlib import Path
from typing import Any, List, Optional

from entity.configs import ConfigError, DesignConfig
from utils.io_utils import read_yaml


def validate_design(data: Any, set_defaults: bool = True, fn_module_ref: Optional[str] = None) -> List[str]:
    """Validate raw YAML data using the typed config loader.
    
    Note: This function validates schema structure only, without resolving
    environment variable placeholders like ${VAR}. This allows workflows to
    be saved even when environment variables are not yet configured - they
    will be resolved at runtime.
    """
    try:
        if not isinstance(data, dict):
            raise ConfigError("YAML root must be a mapping", path="root")
        # Use DesignConfig.from_dict directly to skip placeholder resolution
        # Users may configure environment variables at runtime
        DesignConfig.from_dict(data)
        return []
    except ConfigError as exc:
        return [str(exc)]


def main() -> None:
    parser = argparse.ArgumentParser(description="Validate workflow YAML structure against the typed config loader")
    parser.add_argument("path", help="Path to the workflow YAML file")
    args = parser.parse_args()

    data = read_yaml(args.path)
    errors = validate_design(data)
    if errors:
        print("Design validation failed:")
        for err in errors:

View on GitHub (pinned to 4fb2db0ea9)

Solutions

1. Read the server log entry 'Unexpected error during workflow {action}' for the original traceback.
2. Fix the underlying cause (permissions, disk, path config) in YAML_DIR.
3. Retry the operation once the environment is corrected.

catch (WorkflowExecutionError e) { log.error(e.message); retryOnceAfterEnvFix(); }

When it happens

Trigger: Disk/permission errors while writing YAML, failures in the persist pipeline, or bugs in workflow serialization during upload or update calls.

Common situations: Read-only YAML_DIR in containers; disk full; concurrent writes; schema surprises that pass validation but break persistence.

Related errors

• 1
• 2
• 1
• YAML root must be a mapping
• expected boolean

AI-assisted analysis of OpenBMB/ChatDev@4fb2db0ea9 (2026-08-27). Data as JSON: /api/errors/2282d28802693ec7. Report an issue: GitHub.