bytedance/deer-flow · error · ValueError

agent_name is required to migrate legacy facts

Error message

agent_name is required to migrate legacy facts

What it means

Error "agent_name is required to migrate legacy facts" thrown in bytedance/deer-flow.

Source

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

        for notification_agent, notifications in migration_notifications:
            self._dispatch_retrieval_notifications(notifications, user_id=user_id, agent_name=notification_agent)
        document = self._read_document(path, agent_name, user_id=user_id)
        signature = self._scope_signature(path, agent_name)
        with self._cache_lock:
            self._memory_cache[key] = (copy.deepcopy(document), signature)
        if _rebuild_retrieval and agent_name is not None and self._retrieval is not None:
            self.rebuild_index([{"userId": user_id, "agentName": agent_name}])
        return copy.deepcopy(document)

    def migrate(
        self,
        *,
        user_id: str | None = None,
        agent_name: str | None = None,
    ) -> dict[str, Any]:
        """Run the idempotent version-driven migration for one exact scope."""
        if agent_name is None:
            raise ValueError("agent_name is required to migrate legacy facts")
        path = self._get_memory_file_path(agent_name, user_id=user_id)
        key = self._cache_key(agent_name, user_id=user_id)
        with self._scope_lock(key), _process_file_lock(path.parent / ".memory.lock", float(getattr(self._config, "file_lock_timeout_seconds", 10))):
            self._recover_if_needed(path)
            migrated, from_version, notifications = self._migrate_locked(path, agent_name, user_id=user_id, include_global=True)
        self._dispatch_retrieval_notifications(notifications, user_id=user_id, agent_name=agent_name)
        document = self.reload(agent_name, user_id=user_id, _rebuild_retrieval=False)
        return {
            "migrated": migrated,
            "fromVersion": from_version,
            "toVersion": document.get("version"),
            "revision": document.get("revision", 0),
        }

    def save(
        self,
        memory_data: dict[str, Any],
        agent_name: str | None = None,

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Provide agent_name to the migrate call so facts can be scoped.
2. Migrate per-agent by iterating known agent names.

When it happens

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