langchain-ai/deepagents · critical · RuntimeError

Server process exited with code {process.returncode}

Error message

Server process exited with code {process.returncode}

What it means

`wait_for_server_healthy` in the LangGraph dev-server launcher detects that the spawned server process terminated before responding to health checks. It raises `RuntimeError`, appending any captured stdout/stderr tail and a detected startup-error marker summary so the real cause is visible.

Source

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

    poll_interval = (
        _HEALTH_POLL_INTERVAL_LOCAL if local else _HEALTH_POLL_INTERVAL_REMOTE
    )
    health_url = f"{url}/ok"
    deadline = time.monotonic() + timeout
    last_status: int | None = None
    last_exc: Exception | None = None

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

            try:
                resp = await client.get(health_url, timeout=2)
                if resp.status_code == 200:  # noqa: PLR2004
                    logger.info("Server is healthy at %s", url)
                    return
                last_status = resp.status_code
                logger.debug("Health check returned status %d", resp.status_code)
            except (httpx.TransportError, OSError) as exc:
                logger.debug("Health check attempt failed: %s", exc)
                last_exc = exc

            await asyncio.sleep(poll_interval)

    msg = f"Server did not become healthy within {timeout}s"
    if last_status is not None:
        msg += f" (last status: {last_status})"
    elif last_exc is not None:

View on GitHub (pinned to a1af029e6e)

Solutions

1. Read the stdout/stderr tail appended to the error message — it contains the child process's actual failure
2. Fix the underlying graph/config error surfaced in that output (import error, missing dep, invalid langgraph.json)
3. Verify the server environment/venv has `langgraph-cli` and all graph dependencies installed
4. Run the server command manually in the workspace to reproduce the failure outside the launcher

Example fix

// before
# langgraph.json points to graph:./app/graph.py:graph (module missing)
// after
# correct the path or add the missing module/dependency, then retry launch

import shutil
assert shutil.which("langgraph"), "langgraph CLI not on PATH"
assert (work_dir / "langgraph.json").exists(), "langgraph.json missing"
# Optionally pre-compile graph modules:
compile((graph_path).read_text(), str(graph_path), "exec")

def server_env_ready(work_dir, graph_module) -> bool:
    import importlib.util, shutil
    return (
        shutil.which("langgraph") is not None
        and (work_dir / "langgraph.json").exists()
        and importlib.util.find_spec(graph_module) is not None
    )

try:
    await server._start()
except RuntimeError as e:
    if str(e).startswith("Server process exited with code"):
        logger.error("server boot failed; tail:\n%s", e)
        # fix deps/config surfaced in the tail, then retry once
        await server._start()
    else:
        raise

When it happens

Trigger: During `_start`, the child `langgraph dev` process exits early: missing dependencies, syntax/import errors in graph code, port binding failure at OS level, invalid langgraph.json, or a marked startup error in the output.

Common situations: Graph module has an import error, virtualenv/interpreter mismatch, langgraph CLI missing from the environment, config points at a nonexistent graph, or crash-on-boot from bad env vars.

Related errors

• Server process is not running
• Server process exited with code {self._process.returncode}
• External editor failed
• Hook process pipes are unavailable
• Hook process stdin is unavailable

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