bytedance/deer-flow · error · HTTPException

{label} 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.

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)

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.