bytedance/deer-flow · error · HTTPException

not available

Error message

{label} not available

What it means

Generic 503 raised by the _require() dependency factory when a LangGraph runtime singleton (stream_bridge, run_manager, checkpointer, run_event_store, feedback_repo, run_store) is None on app.state. These singletons are constructed once during lifespan() in langgraph_runtime(); if bootstrap failed or was skipped, every route depending on the getter returns 503 with the label of the missing component.

Solutions

  1. Inspect Gateway startup logs for the bootstrap exception from langgraph_runtime() — the 503 is a downstream symptom, the root cause is at startup
  2. Verify the infrastructure the missing label depends on: DB reachable, data directory writable, migrations applied (`make migrate-rev` / alembic upgrade)
  3. Restart the Gateway after fixing the underlying resource so lifespan() re-runs and re-attaches the singletons
  4. If you mounted Gateway routers into your own FastAPI app, ensure the Gateway lifespan (langgraph_runtime) is composed into your app's lifespan

Example fix

null
Defensive patterns

Strategy: try-catch

Validate before calling

import httpx
r = httpx.get('http://127.0.0.1:8001/health')
r.raise_for_status()  # only call business routes once health confirms lifespan finished

Type guard

null

Try / catch

def safe_call(fn, *a, **kw):
    try:
        return fn(*a, **kw)
    except HTTPException as e:
        if getattr(e, 'status_code', None) == 503 and e.detail.endswith('not available'):
            return None  # treat as 'subsystem down', degrade gracefully
        raise

Prevention

When it happens

Trigger: Calling any /api/* route that Depends() on one of these getters (e.g. run start endpoints needing stream_bridge/run_manager, persistence endpoints needing checkpointer/run_store) when lifespan bootstrap failed — DB connection refused at startup, persistence engine init exception — or when the route is mounted on an app that never ran langgraph_runtime().

Common situations: Database (SQLite/Postgres) unreachable or migration failure during Gateway startup so stores never get attached; a test/secondary FastAPI app mounting Gateway routers without the lifespan context; partial startup where one singleton's constructor raised and was swallowed; checking component health right after start before lifespan finished.

Related errors

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

Appendix: source

Thrown at backend/app/gateway/deps.py:616

                                0.0,
                                shutdown_deadline - asyncio.get_running_loop().time(),
                            ),
                        ),
                    )


# ---------------------------------------------------------------------------
# Getters – called by routers per-request
# ---------------------------------------------------------------------------


def _require(attr: str, label: str) -> Callable[[Request], T]:
    """Create a FastAPI dependency that returns ``app.state.<attr>`` or 503."""

    def dep(request: Request) -> T:
        val = getattr(request.app.state, attr, None)
        if val is None:
            raise HTTPException(status_code=503, detail=f"{label} not available")
        return cast(T, val)

    dep.__name__ = dep.__qualname__ = f"get_{attr}"
    return dep


get_stream_bridge: Callable[[Request], StreamBridge] = _require("stream_bridge", "Stream bridge")
get_run_manager: Callable[[Request], RunManager] = _require("run_manager", "Run manager")
get_checkpointer: Callable[[Request], Checkpointer] = _require("checkpointer", "Checkpointer")
get_run_event_store: Callable[[Request], RunEventStore] = _require("run_event_store", "Run event store")
get_feedback_repo: Callable[[Request], FeedbackRepository] = _require("feedback_repo", "Feedback")
get_run_store: Callable[[Request], RunStore] = _require("run_store", "Run store")


def get_store(request: Request):
    """Return the global store (may be ``None`` if not configured)."""
    return getattr(request.app.state, "store", None)

View on GitHub (pinned to 1dd6ba1acb)