langchain-ai/deepagents · error · RuntimeError

Server graph '{graph_name}' did not initialize within {timeo

Error message

Server graph '{graph_name}' did not initialize within {timeout}s

What it means

Raised from the transport-error branch of `wait_for_graph_ready`: the readiness GET to `/assistants/{graph_name}/graph` failed with httpx.TransportError/TimeoutException/OSError, and while handling it the code found the process still alive, so the graph simply never initialized within `timeout`. The message includes any startup error marker extracted from the server log plus the log tail.

Source

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

                    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:
                        msg += f": {summary}"
                    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"

View on GitHub (pinned to a1af029e6e)

Solutions

1. Inspect the appended server log tail for a startup error marker; fix that error if present
2. Increase the timeout: pass a larger `timeout` to start/wait_for_graph_ready (cold dependency installs can exceed the default)
3. Verify the server bound to the expected host/port matching `self.url`
4. Retry the launch once — transient slowness (uv cache cold) often resolves on second start

Example fix

// before
await manager.start_server_and_get_agent(...)  # 30s default, cold uv sync times out
// after
await manager.start_server_and_get_agent(..., timeout=120.0)  # allow cold install

# ensure the expected port is reachable before starting
import socket
s = socket.socket(); s.settimeout(1)
try:
    s.connect((host, port))
finally:
    s.close()

try:
    await server.wait_for_graph_ready(timeout=120.0)
except RuntimeError as e:
    if "did not initialize" in e.args[0]:
        # inspect log tail in message, then retry once
        ...

When it happens

Trigger: Server is running but never serves the graph endpoint within the timeout — slow first install of runtime dependencies (`uv sync` on cold start), server listening on a different port than `self.url`, connection refused due to a bind mismatch, or an extremely low `timeout` argument passed to wait_for_graph_ready/start.

Common situations: First launch on a slow machine or network where dependency installation exceeds the default health timeout; firewall/antivirus delaying socket binds; custom ports misconfigured so the client polls the wrong URL.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Server did not become healthy within {timeout}s
• Failed while waiting for Vercel sandbox startup.
• Download of {url} exceeded {_DOWNLOAD_TIMEOUT_SECONDS}s dead
• Failed to run git: {redact_urls_in_text(str(exc))}
• Failed to download marketplace from {_redact_url_credentials

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