bytedance/deer-flow · error · MemoryStorageCorruption

Failed to parse canonical fact {path}: {exc}

Error message

Failed to parse canonical fact {path}: {exc}

What it means

Error "Failed to parse canonical fact {path}: {exc}" thrown in bytedance/deer-flow.

Source

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

        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


def _fsync_parent_directory(directory: Path) -> None:
    """Make a completed rename durable on POSIX filesystems."""
    if os.name == "nt":
        return
    descriptor = os.open(directory, os.O_RDONLY)
    try:
        os.fsync(descriptor)
    finally:
        os.close(descriptor)


def _atomic_write(path: Path, raw: bytes) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    temp = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
    try:
        with open(temp, "wb") as handle:

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Fix the YAML/schema error named in the exception inside the fact file.
2. Delete or quarantine the corrupted fact file and let the system rebuild it.

When it happens

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

Common situations: See trigger scenarios.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

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