{"record":{"id":"21ba211ebb1dd118","repo":"langchain-ai/deepagents","slug":"server-process-exited-with-code-process-returncod","errorCode":null,"errorMessage":"Server process exited with code {process.returncode}","messagePattern":"Server process exited with code (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"libs/code/deepagents_code/client/launch/server.py","lineNumber":335,"sourceCode":"    poll_interval = (\n        _HEALTH_POLL_INTERVAL_LOCAL if local else _HEALTH_POLL_INTERVAL_REMOTE\n    )\n    health_url = f\"{url}/ok\"\n    deadline = time.monotonic() + timeout\n    last_status: int | None = None\n    last_exc: Exception | None = None\n\n    async with httpx.AsyncClient() as client:\n        while time.monotonic() < deadline:\n            if process and process.poll() is not None:\n                output = read_log() if read_log else \"\"\n                msg = f\"Server process exited with code {process.returncode}\"\n                if output:\n                    summary = _extract_startup_error_marker(output)\n                    if summary:\n                        msg += f\": {summary}\"\n                    msg += f\"\\n{output[-_LOG_TAIL_CHARS:]}\"\n                raise RuntimeError(msg)\n\n            try:\n                resp = await client.get(health_url, timeout=2)\n                if resp.status_code == 200:  # noqa: PLR2004\n                    logger.info(\"Server is healthy at %s\", url)\n                    return\n                last_status = resp.status_code\n                logger.debug(\"Health check returned status %d\", resp.status_code)\n            except (httpx.TransportError, OSError) as exc:\n                logger.debug(\"Health check attempt failed: %s\", exc)\n                last_exc = exc\n\n            await asyncio.sleep(poll_interval)\n\n    msg = f\"Server did not become healthy within {timeout}s\"\n    if last_status is not None:\n        msg += f\" (last status: {last_status})\"\n    elif last_exc is not None:","sourceCodeStart":317,"sourceCodeEnd":353,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/client/launch/server.py#L317-L353","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the stdout/stderr tail appended to the error message — it contains the child process's actual failure","Fix the underlying graph/config error surfaced in that output (import error, missing dep, invalid langgraph.json)","Verify the server environment/venv has `langgraph-cli` and all graph dependencies installed","Run the server command manually in the workspace to reproduce the failure outside the launcher"],"exampleFix":"// before\n# langgraph.json points to graph:./app/graph.py:graph (module missing)\n// after\n# correct the path or add the missing module/dependency, then retry launch","handlingStrategy":"try-catch","validationCode":"import shutil\nassert shutil.which(\"langgraph\"), \"langgraph CLI not on PATH\"\nassert (work_dir / \"langgraph.json\").exists(), \"langgraph.json missing\"\n# Optionally pre-compile graph modules:\ncompile((graph_path).read_text(), str(graph_path), \"exec\")","typeGuard":"def server_env_ready(work_dir, graph_module) -> bool:\n    import importlib.util, shutil\n    return (\n        shutil.which(\"langgraph\") is not None\n        and (work_dir / \"langgraph.json\").exists()\n        and importlib.util.find_spec(graph_module) is not None\n    )","tryCatchPattern":"try:\n    await server._start()\nexcept RuntimeError as e:\n    if str(e).startswith(\"Server process exited with code\"):\n        logger.error(\"server boot failed; tail:\\n%s\", e)\n        # fix deps/config surfaced in the tail, then retry once\n        await server._start()\n    else:\n        raise","preventionTips":["Always read the stdout/stderr tail attached to the error before guessing","Pre-verify the graph module imports in the target venv","Pin and install langgraph-cli and graph dependencies before launch","Run the server command manually once when onboarding a new workspace"],"tags":["process","server-startup","subprocess"],"backgroundTag":"process-exited-unexpectedly","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}