bytedance/deer-flow · error · Mem0APIError

mem0 {method} {path} -> {resp.status_code}: {resp.text[:200]

Error message

mem0 {method} {path} -> {resp.status_code}: {resp.text[:200]}

What it means

Raised as Mem0APIError by Mem0Client._request when the mem0 server returns any HTTP status >= 400 other than 401 (which is mapped to Mem0AuthError). The message includes method, path, status code, and the first 200 characters of the response body, so the server's own error text is the primary diagnostic.

Source

Thrown at backend/packages/harness/deerflow/agents/memory/backends/mem0/client.py:53

        self._http = httpx.Client(
            base_url=base_url.rstrip("/"),
            headers={"Authorization": f"Token {api_key}", "Accept": "application/json"},
            timeout=timeout_seconds,
            transport=transport,
        )

    def close(self) -> None:
        self._http.close()

    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
        try:
            resp = self._http.request(method, path, **kwargs)
        except httpx.HTTPError as e:
            raise Mem0APIError(f"mem0 request failed: {e}") from e
        if resp.status_code == 401:
            raise Mem0AuthError("mem0 authentication failed (check the API key)")
        if resp.status_code >= 400:
            raise Mem0APIError(f"mem0 {method} {path} -> {resp.status_code}: {resp.text[:200]}")
        if not resp.content:
            return {}
        try:
            return resp.json()
        except json.JSONDecodeError as e:
            raise Mem0APIError(f"mem0 {method} {path} returned malformed JSON: {e}") from e

    def add_memories(
        self,
        *,
        messages: list[dict[str, str]],
        user_id: str | None = None,
        agent_id: str | None = None,
        run_id: str | None = None,
    ) -> dict[str, Any]:
        """Queue extraction (async server-side; response carries an event_id)."""
        body: dict[str, Any] = {"messages": messages}
        if user_id:

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Read the embedded body text — mem0's error message states the exact rejected field or reason
2. Fix base_url: it must be the API root (default https://api.mem0.ai); remove stray path suffixes or add the correct one for a self-hosted server
3. For 4xx: correct the offending parameter (e.g. keep top_k in [1,1000] per local validation, and match the server's own limits)
4. For 5xx: check the mem0 status page / server logs; transient failures are absorbed by failure_policy (default fail_open read / log_and_drop write) or can be retried

Example fix

# before (config.yaml)
memory:
  manager_class: mem0
  backend_config:
    base_url: https://api.mem0.ai/v1   # path duplicated -> 404 on POST /v1/memories/

# after
memory:
  manager_class: mem0
  backend_config:
    base_url: https://api.mem0.ai

from deerflow.agents.memory.backends.mem0.client import Mem0APIError

try:
    resp = client.add_memories(messages=msgs, user_id=u)
except Mem0APIError as e:
    status = int(str(e).split("-> ")[1].split(":")[0]) if "-> " in str(e) else 0
    if 500 <= status < 600:
        time.sleep(2); client.add_memories(messages=msgs, user_id=u)  # transient 5xx: one retry
    else:
        raise   # 4xx is a payload/config bug — fix the request, don't retry

When it happens

Trigger: Any Mem0Client call (POST /v1/memories/ for add_memories, search, get_context) returning 400 (malformed payload / bad parameter), 403, 404 (wrong base_url path prefix), 422, or 5xx from the mem0 service. Example: requesting top_k outside the server's accepted range, or pointing base_url at a path the server does not serve.

Common situations: base_url including or missing a path segment so requests hit a 404; mem0 platform API changed between versions (self-hosted server older/newer than the client expects); a malformed message payload after upstream schema changes; transient 5xx during mem0 incidents.

Related errors

• mem0 request failed: {e}
• mem0 {method} {path} returned malformed JSON: {e}
• agents_api.enabled
• Failed to create agent: ${res.statusText}
• detailMessage ?? `${fallbackMessage}: ${response.statusText}

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