bytedance/deer-flow · error · ValueError

front matter is not a mapping

Error message

front matter is not a mapping

What it means

Error "front matter is not a mapping" thrown in bytedance/deer-flow.

Source

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

    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
    except (OSError, UnicodeError, ValueError, yaml.YAMLError) as exc:
        raise MemoryStorageCorruption(f"Failed to parse canonical fact {path}: {exc}") from exc

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Fix the front matter so it parses as a YAML mapping (key: value lines).
2. Rewrite the fact through the memory API to restore canonical format.

When it happens

Trigger: Thrown at backend/packages/harness/deerflow/agents/memory/backends/deermem/deermem/core/storage.py:297 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/5642754cd6ba9c00. Report an issue: GitHub.