langchain-ai/deepagents · critical · RuntimeError

Server process exited with code {self._process.returncode}

Error message

Server process exited with code {self._process.returncode}

What it means

During readiness polling, `wait_for_graph_ready` checks `self._process.poll()` each iteration; if the subprocess has died it raises this RuntimeError with the exit code, the extracted startup error marker, and the tail of the server log file. The exit code plus log tail is the primary diagnostic for why the LangGraph dev server failed to come up.

Source

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

        if self._process is None:
            msg = "Server process is not running"
            raise RuntimeError(msg)

        graph_url = f"{self.url}/assistants/{quote(graph_name, safe='')}/graph"
        deadline = time.monotonic() + timeout

        async with httpx.AsyncClient() as client:
            while time.monotonic() < deadline:
                if self._process.poll() is not None:
                    msg = f"Server process exited with code {self._process.returncode}"
                    output = self._read_log_file()
                    if output:
                        summary = _extract_startup_error_marker(output)
                        if summary:
                            msg += f": {summary}"
                        msg += f"\n{output[-_LOG_TAIL_CHARS:]}"
                    raise RuntimeError(msg)

                remaining = max(0.1, deadline - time.monotonic())
                try:
                    resp = await client.get(graph_url, timeout=remaining)
                except (httpx.TransportError, httpx.TimeoutException, OSError) as exc:
                    output = self._read_log_file()
                    summary = _extract_startup_error_marker(output)
                    if self._process.poll() is not None:
                        msg = (
                            f"Server process exited with code "
                            f"{self._process.returncode}"
                        )
                    else:
                        msg = (
                            f"Server graph '{graph_name}' did not initialize within "
                            f"{timeout}s"
                        )
                    if summary:

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Read the log tail appended to the message — it usually contains the actual traceback or startup error marker
  2. Fix the underlying server error indicated in the log (import error, missing dependency, port conflict)
  3. Run with DEEPAGENTS_CODE_DEBUG=1 for full server logs and restart via restart()/respawn
  4. Verify langgraph.json and the graph module resolve in the server's generated work directory
Defensive patterns

Strategy: try-catch

Try / catch

try:
    await server.wait_for_graph_ready()
except RuntimeError as e:
    if e.args[0].startswith("Server process exited"):
        log_tail = e.args[0].split("\n", 1)[-1]  # diagnose from appended log
        # fix underlying cause, then restart
    raise

Prevention

When it happens

Trigger: The spawned `langgraph dev` subprocess exits (non-zero or otherwise) while `wait_for_graph_ready` is polling — e.g. bad `langgraph.json`, missing dependencies in the generated runtime, import errors in graph code, port conflicts, or an invalid MCP config that slipped past preflight.

Common situations: Syntax/import errors in the user's agent module; missing optional provider packages in the server runtime venv; port already bound by another process; corrupted or missing config in the generated work directory.

Related errors

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