langchain-ai/deepagents · error · RuntimeError

Failed to list blueprints: {e}

Error message

Failed to list blueprints: {e}

What it means

`_ensure_blueprint` lists Runloop blueprints via the SDK client to find one matching the requested name, and wraps any exception from `client.blueprints.list` in a `RuntimeError` with the upstream message chained (`from e`). This converts provider/API failures (auth, network, pagination errors) into a consistent library-level error.

Source

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

        blueprint_name: Blueprint name to resolve or create.
        dockerfile: Dockerfile used when creating a new blueprint.

    Raises:
        RuntimeError: If listing or building fails, or a same-name blueprint
            exists but is not ready.
    """
    non_ready_status: str | None = None
    starting_after: str | None = None

    while True:
        list_kwargs: dict[str, Any] = {"name": blueprint_name, "limit": 100}
        if starting_after is not None:
            list_kwargs["starting_after"] = starting_after
        try:
            page = client.blueprints.list(**list_kwargs)
        except Exception as e:
            msg = f"Failed to list blueprints: {e}"
            raise RuntimeError(msg) from e

        for blueprint in page.blueprints:
            if blueprint.name != blueprint_name:
                continue
            if blueprint.status == "build_complete":
                return
            non_ready_status = blueprint.status

        if not page.has_more or not page.blueprints:
            break
        starting_after = page.blueprints[-1].id

    if non_ready_status is not None:
        raise RuntimeError(_not_ready_message(blueprint_name, non_ready_status))

    try:
        client.blueprints.create_and_await_build_complete(
            name=blueprint_name,

View on GitHub (pinned to a1af029e6e)

Solutions

1. Read the chained exception (`raise ... from e`) to see the root cause; fix auth if it is 401/403 by setting a valid Runloop API key.
2. Retry on transient network/5xx errors with backoff; list is idempotent.
3. Verify network/egress to the Runloop API from your environment (proxy, DNS, firewall).
4. If a pagination cursor is involved, restart listing from the beginning instead of a stale `starting_after`.

Example fix

// before
bp = provider._ensure_blueprint(client, "my-blueprint")  # opaque RuntimeError on API failure

// after
try:
    bp = provider._ensure_blueprint(client, "my-blueprint")
except RuntimeError as e:
    logger.exception("blueprint listing failed: %s", e.__cause__)
    if is_transient(e.__cause__):
        bp = retry_with_backoff(provider._ensure_blueprint, client, "my-blueprint")
    else:
        raise

import os
if not os.environ.get("RUNLOOP_API_KEY"):
    raise RuntimeError("RUNLOOP_API_KEY is not set; blueprint listing will fail")

try:
    ensure_blueprint(client, name)
except RuntimeError as e:
    cause = e.__cause__
    if is_transient_network_error(cause):
        ensure_blueprint_with_backoff(client, name)
    elif is_auth_error(cause):
        raise ConfigError("check RUNLOOP_API_KEY") from cause
    else:
        raise

When it happens

Trigger: Calling eval/bootstrap code that needs a blueprint when `client.blueprints.list()` raises — e.g. an invalid or expired Runloop API key, network outage, rate limiting, or a malformed `starting_after` pagination cursor.

Common situations: Missing or rotated `RUNLOOP_API_KEY`; expired credentials; corporate proxy/firewall blocking api.runloop.ai; transient 5xx or rate-limit responses during CI; a blueprint list page cursor that no longer exists.

Related errors

• Blueprint '{blueprint_name}' exists but its last build faile
• Failed to build blueprint '{blueprint_name}': {create_err}
• Runloop API unreachable (transient — safe to retry): {e}
• Blueprint name is required when no blueprint ID is set
• Server did not become healthy within {timeout}s

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