bytedance/deer-flow · error · ValueError

missing YAML front matter

Error message

missing YAML front matter

What it means

Error "missing YAML front matter" thrown in bytedance/deer-flow.

Source

Thrown at backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py:293

    return (first or "Memory fact")[:160]


def _render_fact_markdown(fact: dict[str, Any]) -> bytes:
    metadata = {key: copy.deepcopy(value) for key, value in fact.items() if key not in {"content", "title"}}
    scope = metadata.pop("scope", {})
    if isinstance(scope, dict):
        metadata["user_id"] = scope.get("userId")
        metadata["agent_name"] = scope.get("agentName")
    front_matter = yaml.safe_dump(metadata, allow_unicode=True, sort_keys=False).strip()
    text = f"---\n{front_matter}\n---\n\n# {_fact_title(fact)}\n\n{fact['content'].rstrip()}\n"
    return text.encode("utf-8")


def _parse_fact_markdown(path: Path) -> dict[str, Any]:
    try:
        text = path.read_text(encoding="utf-8")
        if not text.startswith("---\n"):
            raise ValueError("missing YAML front matter")
        front, body = text[4:].split("\n---\n", 1)
        metadata = yaml.safe_load(front) or {}
        if not isinstance(metadata, dict):
            raise ValueError("front matter is not a mapping")
        body = body.lstrip("\n")
        lines = body.splitlines()
        title = ""
        if lines and lines[0].startswith("# "):
            title = lines.pop(0)[2:].strip()
            if lines and not lines[0].strip():
                lines.pop(0)
        metadata["title"] = title
        metadata["content"] = "\n".join(lines).rstrip("\n")
        metadata["scope"] = {
            "userId": metadata.pop("user_id", None),
            "agentName": metadata.pop("agent_name", None),
        }
        return metadata

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Add YAML front matter (--- delimited block) to the fact file.
2. Regenerate the fact via the memory API so it is written in canonical format.

When it happens

Trigger: Thrown at backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py:293 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/545a38350982ac6a. Report an issue: GitHub.