bytedance/deer-flow · error · HonchoRequestError

Honcho request failed: POST {path}: {exc}

Error message

Honcho request failed: POST {path}: {exc}

What it means

Honcho memory backend HTTP client wraps every httpx.HTTPError from a POST (connect failure, timeout, DNS error, 4xx/5xx via raise_for_status) in HonchoRequestError with the path and underlying exception. It is the single failure type for all Honcho REST calls (peer/session creation, message ingestion, query).

Source

Thrown at backend/packages/harness/deerflow/agents/memory/backends/honcho/client.py:43

        headers = {"Content-Type": "application/json"}
        if config.api_key:
            headers["Authorization"] = f"Bearer {config.api_key}"
        self._http = httpx.Client(
            base_url=config.base_url,
            headers=headers,
            timeout=httpx.Timeout(config.timeout_seconds, connect=config.connect_timeout_seconds),
            transport=transport,
        )

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

    def _post(self, path: str, payload: Any) -> Any:
        try:
            response = self._http.post(path, json=payload)
            response.raise_for_status()
        except httpx.HTTPError as exc:
            raise HonchoRequestError(f"Honcho request failed: POST {path}: {exc}") from exc
        if response.content:
            try:
                return response.json()
            except ValueError as exc:
                raise HonchoRequestError(f"Honcho returned non-JSON response: POST {path}: {exc}") from exc
        return None

    def get_or_create_peer(self, workspace: str, peer_id: str) -> None:
        self._post(f"/v3/workspaces/{workspace}/peers", {"id": peer_id})

    def get_or_create_session(self, workspace: str, session_id: str) -> None:
        self._post(f"/v3/workspaces/{workspace}/sessions", {"id": session_id})

    def set_session_peers(self, workspace: str, session_id: str, peer_ids: list[str]) -> None:
        self._post(f"/v3/workspaces/{workspace}/sessions/{session_id}/peers", {peer_id: {} for peer_id in peer_ids})

    def add_messages(self, workspace: str, session_id: str, messages: list[dict[str, str]]) -> None:
        self._post(f"/v3/workspaces/{workspace}/sessions/{session_id}/messages", {"messages": messages})

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Verify the Honcho service URL and reachability (curl the base URL from the Gateway host)
2. Check the API key/auth headers are set and valid (401/403 in the chained exception)
3. Retry with backoff for transient 5xx/timeouts; the client does not retry internally
4. Raise config timeout_seconds / connect_timeout_seconds if timeouts recur

def honcho_reachable(base_url: str, timeout: float = 3.0) -> bool:
    try:
        httpx.get(base_url, timeout=timeout)
        return True
    except httpx.HTTPError:
        return False

from deerflow.agents.memory.backends.honcho.client import HonchoRequestError

for attempt in range(3):
    try:
        client.add_messages(workspace, session_id, messages)
        break
    except HonchoRequestError as e:
        if attempt == 2 or "401" in str(e) or "403" in str(e):
            raise
        time.sleep(0.5 * (2 ** attempt))

When it happens

Trigger: Honcho base URL wrong or unreachable (connection refused), timeouts on slow queries, expired/invalid API key returning 401/403, workspace id returning 404, or the Honcho service being down.

Common situations: Wrong HONCHO_BASE_URL in env, missing API key header, local Honcho container not started, transient network blips, or rate limiting (429).

Related errors

• Honcho returned non-JSON response: POST {path}: {exc}
• Honcho backend: api_key over plain http requires backend_con
• honcho memory recall failed: {exc}
• mem0 request failed: {e}
• agents_api.enabled

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