langchain-ai/deepagents · error · RuntimeError

Server graph '{graph_name}' failed readiness check (status:

Error message

Server graph '{graph_name}' failed readiness check (status: {resp.status_code})

What it means

`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).

Source

Thrown at libs/code/deepagents_code/client/launch/server.py:1060

                    if output:
                        msg += f"\n{output[-_LOG_TAIL_CHARS:]}"
                    raise RuntimeError(msg) from exc

                if resp.status_code == 200:  # noqa: PLR2004
                    logger.info("Server graph %s is ready at %s", graph_name, self.url)
                    return

                output = self._read_log_file()
                msg = (
                    f"Server graph '{graph_name}' failed readiness check "
                    f"(status: {resp.status_code})"
                )
                summary = _extract_startup_error_marker(output)
                if summary:
                    msg += f": {summary}"
                if output:
                    msg += f"\n{output[-_LOG_TAIL_CHARS:]}"
                raise RuntimeError(msg)

        msg = f"Server graph '{graph_name}' did not initialize within {timeout}s"
        raise RuntimeError(msg)

    def _stop_process(self) -> None:
        """Stop only the server subprocess and its log file.

        Unlike `stop()`, this does NOT clean up the config directory or temp
        directory, so the server can be restarted with the same config.
        """
        with self._state_lock:
            self._stop_process_locked()

    def _stop_process_locked(self) -> None:
        """Stop the subprocess while `_state_lock` is held."""
        if self._process is None:
            return

View on GitHub (pinned to a1af029e6e)

Solutions

1. Check the status code in the message: 404 usually means the graph name is wrong; 5xx means graph load failed
2. Verify graph_name matches a key in the langgraph.json used by the server
3. Read the log tail in the message for the graph import/initialization traceback
4. If behind a proxy, bypass it or ensure it forwards to the correct dev-server port

Example fix

// before
await server.wait_for_graph_ready(graph_name="agent")  # 404: graph not registered
// after
await server.wait_for_graph_ready(graph_name="agent")  # ensure langgraph.json has {"graphs": {"agent": "./agent.py:graph"}}

try:
    await server.wait_for_graph_ready(graph_name="agent")
except RuntimeError as e:
    if "failed readiness check" in e.args[0]:
        status = e.args[0].rsplit("status: ", 1)[-1].rstrip(")")
        if status == "404":
            # wrong graph name: fix graph_name / langgraph.json
        ...
    raise

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Server did not become healthy within {timeout}s
• Server process exited with code {self._process.returncode}
• thread_id is required in config.configurable
• Pending graph work remained on thread {thread_id} after clea
• Device code request failed: HTTP {response.status_code} from

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/04b462357a313240. Report an issue: GitHub.