OpenBMB/ChatDev · error · ValueError

frontmatter must be a mapping

Error message

frontmatter must be a mapping

What it means

Once the frontmatter block is extracted, _parse_frontmatter yaml.safe_loads it and requires the result to be a Mapping. A YAML scalar or list at the top level (e.g. a bare string or '- a' sequence) raises ValueError('frontmatter must be a mapping').

Source

Thrown at entity/configs/node/skills.py:62

    return discovered


def _parse_frontmatter(skill_file: Path) -> Mapping[str, object]:
    text = skill_file.read_text(encoding="utf-8")
    if not text.startswith("---"):
        raise ValueError("missing frontmatter")
    lines = text.splitlines()
    end_idx = None
    for idx in range(1, len(lines)):
        if lines[idx].strip() == "---":
            end_idx = idx
            break
    if end_idx is None:
        raise ValueError("missing closing delimiter")
    payload = "\n".join(lines[1:end_idx])
    data = yaml.safe_load(payload) or {}
    if not isinstance(data, Mapping):
        raise ValueError("frontmatter must be a mapping")
    return data


@dataclass
class AgentSkillSelectionConfig(BaseConfig):
    name: str

    FIELD_SPECS = {
        "name": ConfigFieldSpec(
            name="name",
            display_name="Skill Name",
            type_hint="str",
            required=True,
            description="Discovered skill name from the default repo-level skills directory.",
        ),
    }

    @classmethod

View on GitHub (pinned to 4fb2db0ea9)

Solutions

1. Rewrite frontmatter as key: value mappings (name:, description:, ...), one pair per line
2. Validate the block with a YAML linter before shipping
3. Check for missing colons or misindentation that degrade the mapping

Example fix

# before
---
my-skill
---
# after
---
name: my-skill
description: does a thing
---

import yaml
payload = text.split('---')[1]
data = yaml.safe_load(payload)
assert isinstance(data, dict), 'frontmatter must be key: value YAML'

try:
    _discover_default_skills(skills_dir)
except ValueError as e:
    if 'must be a mapping' in str(e):
        # rewrite file frontmatter from a default template
        ...

When it happens

Trigger: Skill frontmatter whose top-level YAML is a scalar (e.g. just 'my-skill') or a sequence ('- name: x') instead of key: value pairs.

Common situations: Authors writing a title line instead of key-value metadata; YAML syntax errors that make safe_load return a string; list-style frontmatter borrowed from other tools.

Related errors

• missing frontmatter
• missing closing delimiter
• 1
• 2
• YAML root must be a mapping

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