langchain-ai/deepagents · error · RuntimeError

Failed to create Runloop devbox from '{target}': {e}

Error message

Failed to create Runloop devbox from '{target}': {e}

What it means

The catch-all in `get_or_create`: any exception from devbox creation or blueprint boot that is not auth-, permission-, connection-, or timeout-related is re-raised as a `RuntimeError` naming the creation target — the blueprint name, blueprint ID, or literally `'devbox'` for a plain create. It wraps underlying SDK/API errors so callers only need to handle `RuntimeError`, while the original exception is preserved via `raise ... from`.

Source

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

                    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"
            raise RuntimeError(msg)
        _ensure_blueprint(self._client, blueprint_name, dockerfile=dockerfile)
        return self._sdk.devbox.create_from_blueprint_name(blueprint_name)

View on GitHub (pinned to a1af029e6e)

Solutions

1. Inspect `e.__cause__` (or the embedded message) for the underlying API error and status code.
2. If the cause is 429/quota, delete unused devboxes (`provider.delete(sandbox_id=...)`) or wait, then retry.
3. If the cause mentions the blueprint ID, verify `RUNLOOP_SANDBOX_BLUEPRINT_ID` in the Runloop dashboard; fall back to name-based `snapshot=`.
4. If transient (5xx), retry with backoff.
5. Simplify to `provider.get_or_create()` (empty devbox) to isolate whether the blueprint path is the problem.

Example fix

// before
sandbox = provider.get_or_create()  # RuntimeError: Failed to create Runloop devbox from 'devbox': 429

// after
try:
    sandbox = provider.get_or_create()
except RuntimeError as e:
    if "429" in str(e):
        for old in provider.list_sandboxes():  # free quota
            provider.delete(sandbox_id=old.id)
        sandbox = provider.get_or_create()
    else:
        raise

def blueprint_id_env_valid(value: str | None) -> bool:
    return bool(value) and value.startswith("bp_")  # adjust to real ID prefix

try:
    sandbox = provider.get_or_create(snapshot="my-bp")
except RuntimeError as e:
    cause = e.__cause__
    if cause is not None and "429" in str(cause):
        backoff_and_retry()
    else:
        log.error("devbox creation from %s failed: %s", e, cause)
        raise

When it happens

Trigger: `get_or_create` create path where the Runloop SDK raises anything else — e.g. `create_from_blueprint_id` with a nonexistent/invalid blueprint ID, quota/capacity errors (4xx/5xx responses), rate limiting, or an invalid blueprint name rejected by the API.

Common situations: `RUNLOOP_SANDBOX_BLUEPRINT_ID` pointing at a deleted blueprint; org quota exhausted for concurrent devboxes; API returning 500s or 429s; malformed snapshot/blueprint name characters.

Related errors

• Failed to list blueprints: {e}
• Blueprint '{blueprint_name}' exists but its last build faile
• Failed to build blueprint '{blueprint_name}': {create_err}
• {sandbox_id}
• Runloop rejected the credentials; check RUNLOOP_API_KEY (or

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