OpenBMB/ChatDev · warning · ConfigError

YAML root must be a mapping

Error message

YAML root must be a mapping

What it means

ResourceNotFoundError raised by the workflow-args endpoint when the YAML parses and the top-level graph dict exists but its args list is empty. The endpoint requires at least one declared argument to return.

Source

Thrown at entity/config_loader.py:32

    load_dotenv_file()
    env_lookup = build_env_var_map()
    prepared = dict(data)
    resolve_design_placeholders(prepared, env_lookup=env_lookup, path=source or "root")
    return prepared


def load_design_from_mapping(data: Mapping[str, Any], *, source: str | None = None) -> DesignConfig:
    """Parse a raw dictionary into a typed :class:`DesignConfig`."""
    prepared = prepare_design_mapping(data, source=source)
    return DesignConfig.from_dict(prepared, path="root")


def load_design_from_file(path: Path) -> DesignConfig:
    """Read a YAML file and parse it into a :class:`DesignConfig`."""
    with path.open("r", encoding="utf-8") as handle:
        data = yaml.load(handle, Loader=yaml.FullLoader)
    if not isinstance(data, Mapping):
        raise ConfigError("YAML root must be a mapping", path=str(path))
    return load_design_from_mapping(data, source=str(path))

View on GitHub (pinned to 4fb2db0ea9)

Solutions

1. Add an args list under 'graph:' in the workflow YAML (or remove the args block entirely if graph has no args key, but note empty list errors).
2. Validate your YAML with the same check the server uses before deploying.
3. If the workflow is intentionally arg-less, don't call the args endpoint for it.

Example fix

# before
graph:
  args: []
# after
graph:
  args:
    - param_name:
        - type: string
          required: true

const doc = jsYaml.load(content);
const args = doc?.graph?.args;
if (!Array.isArray(args) || args.length === 0) skipArgsFetch(name);

function hasWorkflowArgs(doc: any): boolean { return Array.isArray(doc?.graph?.args) && doc.graph.args.length > 0; }

catch (e) { if (e.status === 404 && /args/.test(e.detail)) renderNoArgsPlaceholder(); }

When it happens

Trigger: GET args for a workflow YAML like 'graph:\n args: []' or one where the graph key simply omits/empties args, or where graph is not shaped as expected so raw_args ends up empty.

Common situations: Workflows written without parameterization; refactors that moved args elsewhere in the schema; copy-pasted templates missing the args block.

Related errors

• 2
• 1
• Invalid YAML syntax: {exc}
• 1
• YAML root must be a mapping

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