{"record":{"id":"c7d05d24e304ef71","repo":"bytedance/deer-flow","slug":"label-not-available","errorCode":null,"errorMessage":"{label} not available","messagePattern":"(.+?) not available","errorType":"http","errorClass":"HTTPException","httpStatus":503,"severity":"error","filePath":"backend/app/gateway/deps.py","lineNumber":616,"sourceCode":"                                0.0,\n                                shutdown_deadline - asyncio.get_running_loop().time(),\n                            ),\n                        ),\n                    )\n\n\n# ---------------------------------------------------------------------------\n# Getters – called by routers per-request\n# ---------------------------------------------------------------------------\n\n\ndef _require(attr: str, label: str) -> Callable[[Request], T]:\n    \"\"\"Create a FastAPI dependency that returns ``app.state.<attr>`` or 503.\"\"\"\n\n    def dep(request: Request) -> T:\n        val = getattr(request.app.state, attr, None)\n        if val is None:\n            raise HTTPException(status_code=503, detail=f\"{label} not available\")\n        return cast(T, val)\n\n    dep.__name__ = dep.__qualname__ = f\"get_{attr}\"\n    return dep\n\n\nget_stream_bridge: Callable[[Request], StreamBridge] = _require(\"stream_bridge\", \"Stream bridge\")\nget_run_manager: Callable[[Request], RunManager] = _require(\"run_manager\", \"Run manager\")\nget_checkpointer: Callable[[Request], Checkpointer] = _require(\"checkpointer\", \"Checkpointer\")\nget_run_event_store: Callable[[Request], RunEventStore] = _require(\"run_event_store\", \"Run event store\")\nget_feedback_repo: Callable[[Request], FeedbackRepository] = _require(\"feedback_repo\", \"Feedback\")\nget_run_store: Callable[[Request], RunStore] = _require(\"run_store\", \"Run store\")\n\n\ndef get_store(request: Request):\n    \"\"\"Return the global store (may be ``None`` if not configured).\"\"\"\n    return getattr(request.app.state, \"store\", None)\n","sourceCodeStart":598,"sourceCodeEnd":634,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/deps.py#L598-L634","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","solutions":["Inspect Gateway startup logs for the bootstrap exception from langgraph_runtime() — the 503 is a downstream symptom, the root cause is at startup","Verify the infrastructure the missing label depends on: DB reachable, data directory writable, migrations applied (`make migrate-rev` / alembic upgrade)","Restart the Gateway after fixing the underlying resource so lifespan() re-runs and re-attaches the singletons","If you mounted Gateway routers into your own FastAPI app, ensure the Gateway lifespan (langgraph_runtime) is composed into your app's lifespan"],"exampleFix":"null","handlingStrategy":"try-catch","validationCode":"import httpx\nr = httpx.get('http://127.0.0.1:8001/health')\nr.raise_for_status()  # only call business routes once health confirms lifespan finished","typeGuard":"null","tryCatchPattern":"def safe_call(fn, *a, **kw):\n    try:\n        return fn(*a, **kw)\n    except HTTPException as e:\n        if getattr(e, 'status_code', None) == 503 and e.detail.endswith('not available'):\n            return None  # treat as 'subsystem down', degrade gracefully\n        raise","preventionTips":["Gate clients on /health before issuing API calls","Treat any '<label> not available' 503 as a startup defect: read Gateway startup logs, don't retry-loop","In tests, always run Gateway routers under the real lifespan fixture"],"tags":["http-503","lifespan","startup","dependency-injection","gateway"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}