What causes "Runloop API unreachable (transient — safe to retry): {e}" in langchain-ai/deepagents?

Retry the same `get_or_create` call with exponential backoff — the error is explicitly safe to retry.

langchain-ai/deepagents · error · RuntimeError

Runloop API unreachable (transient — safe to retry): {e}

Error message

Runloop API unreachable (transient — safe to retry): {e}

What it means

Raised when the Runloop API raises `APIConnectionError` or `APITimeoutError` while creating a devbox or booting from a blueprint. The message explicitly states the failure is transient and safe to retry — the request never reached Runloop or timed out before a definitive answer, so no partial state needs cleanup.

Source

Thrown at libs/partners/runloop/langchain_runloop/provider.py:216

        try:
            if use_blueprint:
                devbox = self._create_from_blueprint(
                    blueprint_id=env_blueprint_id,
                    blueprint_name=blueprint_name,
                    dockerfile=dockerfile,
                )
            else:
                devbox = self._sdk.devbox.create()
        except (AuthenticationError, PermissionDeniedError) as e:
            msg = (
                "Runloop rejected the credentials; check RUNLOOP_API_KEY "
                f"(or DEEPAGENTS_CODE_RUNLOOP_API_KEY): {e}"
            )
            raise RuntimeError(msg) from e
        except (APIConnectionError, APITimeoutError) as e:
            msg = f"Runloop API unreachable (transient — safe to retry): {e}"
            raise RuntimeError(msg) from e
        except Exception as e:
            target = blueprint_name or env_blueprint_id or "devbox"
            msg = f"Failed to create Runloop devbox from '{target}': {e}"
            raise RuntimeError(msg) from e

        return RunloopSandbox(devbox=devbox)

    def _create_from_blueprint(
        self,
        *,
        blueprint_id: str | None,
        blueprint_name: str | None,
        dockerfile: str,
    ) -> Devbox:
        if blueprint_id is not None:
            return self._sdk.devbox.create_from_blueprint_id(blueprint_id)
        if blueprint_name is None:
            msg = "Blueprint name is required when no blueprint ID is set"

View on GitHub (pinned to a1af029e6e)

Solutions

Retry the same `get_or_create` call with exponential backoff — the error is explicitly safe to retry.
Check network egress/proxy settings (`HTTPS_PROXY`) and Runloop's status page for incidents.
Increase the HTTP client timeout if blueprint boot is slow (pass a configured client / raise timeout).
If blueprint boot times out repeatedly, boot by blueprint ID (`RUNLOOP_SANDBOX_BLUEPRINT_ID`) or use an empty devbox, then install dependencies at runtime.
Verify DNS resolution of the Runloop API host from the failing environment.

Example fix

// before
sandbox = provider.get_or_create(snapshot="my-bp")  # may raise on flaky network

// after
import time
for attempt in range(5):
    try:
        sandbox = provider.get_or_create(snapshot="my-bp")
        break
    except RuntimeError as e:
        if "transient" not in str(e) or attempt == 4:
            raise
        time.sleep(2 ** attempt)

Defensive patterns

Strategy: retry

Validate before calling

import socket

def runloop_api_reachable(host: str = "api.runloop.com", timeout: float = 5.0) -> bool:
    try:
        socket.create_connection((host, 443), timeout=timeout).close()
        return True
    except OSError:
        return False

Try / catch

import time

for attempt in range(5):
    try:
        sandbox = provider.get_or_create(snapshot="my-bp")
        break
    except RuntimeError as e:
        if "transient" not in str(e):
            raise
        time.sleep(min(2 ** attempt, 30))
else:
    raise

Prevention

Wrap create calls in exponential-backoff retries — the message guarantees idempotent retry safety.
Configure HTTPS_PROXY / egress rules so CI and containers can reach api.runloop.com.
Monitor Runloop's status page and gate job startup on API health checks.
Raise HTTP timeouts for long blueprint boots, or pre-build blueprints and boot by ID.

When it happens

Trigger: `get_or_create` create path executed while the network to api.runloop.com is down, a proxy/firewall blocks it, DNS fails, or the request exceeds the client's timeout during devbox creation or blueprint boot.

Common situations: Corporate proxy requiring configuration; VPN dropouts; CI runner egress restrictions; Runloop incident/outage; overly tight HTTP timeout on slow blueprint boots.

Related errors

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