{"record":{"id":"04b462357a313240","repo":"langchain-ai/deepagents","slug":"server-graph-graph-name-failed-readiness-check","errorCode":null,"errorMessage":"Server graph '{graph_name}' failed readiness check (status: {resp.status_code})","messagePattern":"Server graph '(.+?)' failed readiness check \\(status: (.+?)\\)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/client/launch/server.py","lineNumber":1060,"sourceCode":"                    if output:\n                        msg += f\"\\n{output[-_LOG_TAIL_CHARS:]}\"\n                    raise RuntimeError(msg) from exc\n\n                if resp.status_code == 200:  # noqa: PLR2004\n                    logger.info(\"Server graph %s is ready at %s\", graph_name, self.url)\n                    return\n\n                output = self._read_log_file()\n                msg = (\n                    f\"Server graph '{graph_name}' failed readiness check \"\n                    f\"(status: {resp.status_code})\"\n                )\n                summary = _extract_startup_error_marker(output)\n                if summary:\n                    msg += f\": {summary}\"\n                if output:\n                    msg += f\"\\n{output[-_LOG_TAIL_CHARS:]}\"\n                raise RuntimeError(msg)\n\n        msg = f\"Server graph '{graph_name}' did not initialize within {timeout}s\"\n        raise RuntimeError(msg)\n\n    def _stop_process(self) -> None:\n        \"\"\"Stop only the server subprocess and its log file.\n\n        Unlike `stop()`, this does NOT clean up the config directory or temp\n        directory, so the server can be restarted with the same config.\n        \"\"\"\n        with self._state_lock:\n            self._stop_process_locked()\n\n    def _stop_process_locked(self) -> None:\n        \"\"\"Stop the subprocess while `_state_lock` is held.\"\"\"\n        if self._process is None:\n            return\n","sourceCodeStart":1042,"sourceCodeEnd":1078,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/client/launch/server.py#L1042-L1078","documentation":"`wait_for_graph_ready` got an HTTP response from the graph endpoint but with a non-200 status; it immediately raises this RuntimeError with the status code, any extracted startup error marker, and the log tail. Unlike the timeout path, the server answered — it just reported the graph is not available/healthy (e.g. 404 for unknown graph, 500 for graph load failure).","triggerScenarios":"Graph name not present in the server's langgraph.json (404); the graph module raised on import/initialization so the server returns 500; auth/proxy in front of the server rejecting the request (401/403).","commonSituations":"Passing a graph_name that does not match the key registered in langgraph.json; a runtime error in the assistant factory function; reverse-proxy or port-forward returning 502/503 while the dev server restarts.","solutions":["Check the status code in the message: 404 usually means the graph name is wrong; 5xx means graph load failed","Verify graph_name matches a key in the langgraph.json used by the server","Read the log tail in the message for the graph import/initialization traceback","If behind a proxy, bypass it or ensure it forwards to the correct dev-server port"],"exampleFix":"// before\nawait server.wait_for_graph_ready(graph_name=\"agent\")  # 404: graph not registered\n// after\nawait server.wait_for_graph_ready(graph_name=\"agent\")  # ensure langgraph.json has {\"graphs\": {\"agent\": \"./agent.py:graph\"}}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    await server.wait_for_graph_ready(graph_name=\"agent\")\nexcept RuntimeError as e:\n    if \"failed readiness check\" in e.args[0]:\n        status = e.args[0].rsplit(\"status: \", 1)[-1].rstrip(\")\")\n        if status == \"404\":\n            # wrong graph name: fix graph_name / langgraph.json\n        ...\n    raise","preventionTips":["Keep graph_name in sync with the key registered in langgraph.json","Smoke-test the graph module imports in the server's Python env","Bypass or correctly configure proxies in front of the dev server"],"tags":["http","health-check","langgraph"],"backgroundTag":"health-check-failed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}