bytedance/deer-flow · critical · MemoryManagerError

OpenViking health check returned an unhealthy response

Error message

OpenViking health check returned an unhealthy response

What it means

During startup validation, OpenVikingMemoryManager calls the SDK client's health() and, if it returns a falsy result while startup_policy is 'fail_fast' (the default), raises MemoryManagerError. This is a deliberate fail-fast: an unavailable OpenViking service should abort rather than silently run without memory. Note the distinction: an exception from health() under fail_fast re-raises the original exception; this specific message means health() was callable, returned, and reported unhealthy.

Source

Thrown at backend/packages/harness/deerflow/agents/memory/backends/openviking/openviking_manager.py:281

        )

    def warm(self) -> bool | None:
        if not self._begin_operation():
            return False
        try:
            try:
                health = getattr(self._client, "health", None)
                healthy = bool(health()) if callable(health) else True
            except Exception:
                if self._config.startup_policy == "fail_fast":
                    raise
                logger.warning(
                    "OpenViking startup validation failed; memory will run in degraded mode",
                    exc_info=True,
                )
                return False
            if not healthy and self._config.startup_policy == "fail_fast":
                raise MemoryManagerError("OpenViking health check returned an unhealthy response")
            if not healthy:
                logger.warning("OpenViking health check returned unhealthy; memory will run in degraded mode")
            return healthy
        finally:
            self._end_operation()

    def shutdown_flush(self, timeout: float) -> bool:
        """Stop new work, drain accepted calls, and close owned resources."""

        deadline = time.monotonic() + max(0.0, timeout)
        with self._lifecycle:
            self._closed = True
            self._close_requested = True
            while self._active_operations:
                remaining = deadline - time.monotonic()
                if remaining <= 0:
                    return False
                self._lifecycle.wait(remaining)

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Check the OpenViking service is actually healthy: query its health endpoint at the configured base_url directly
2. Fix the service (restart it, check its logs, wait for migrations) and restart the Gateway
3. If degraded-mode startup is acceptable, set memory.backend_config.startup_policy: warn — memory recall will then be skipped/logged while the service is unhealthy

Example fix

# before (config.yaml)
memory:
  manager_class: openviking
  backend_config:
    startup_policy: fail_fast   # Gateway refuses to start while OpenViking is unhealthy

# after (accept degraded boot)
memory:
  manager_class: openviking
  backend_config:
    startup_policy: warn

# Pre-startup probe: verify OpenViking answers before booting the Gateway with fail_fast
import urllib.request
with urllib.request.urlopen(f"{base_url}/health", timeout=5) as resp:
    assert resp.status == 200, f"OpenViking unhealthy: HTTP {resp.status}"

from deerflow.agents.memory.manager import MemoryManagerError
try:
    manager = OpenVikingMemoryManager.from_config(cfg)
except MemoryManagerError as exc:
    if "unhealthy" in str(exc):
        deploy_degraded()  # or wait/retry after fixing the OpenViking service
    raise

When it happens

Trigger: OpenVikingConfig.startup_policy == 'fail_fast' (default) and the OpenViking service at base_url answers its health endpoint as unhealthy — service up but degraded, wrong build, or a proxy returning an unhealthy status. Happens during manager startup validation, i.e. Gateway boot / agent rebuild.

Common situations: OpenViking container starting but failing its own readiness (schema migration pending, dependency down), or base_url pointing at the wrong service/port that responds with an error payload to the health call.

Related errors

• DeerMem memory update requested but no LLM is configured (se
• OpenViking startup_policy must be 'fail_fast' or 'warn'
• OpenViking memory write requires thread_id
• OpenViking USER API key is bound to DeerFlow owner_user_id {
• OpenViking capture cursor is unreadable; refusing unsafe rep

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