langchain-ai/deepagents · error · RuntimeError

Failed to build blueprint '{blueprint_name}': {create_err}

Error message

Failed to build blueprint '{blueprint_name}': {create_err}

What it means

Raised by `_ensure_blueprint` when `client.blueprints.create_and_await_build_complete(...)` throws while creating or building a new blueprint that did not already exist by name. The original SDK exception is preserved via `raise ... from`, and the message embeds the blueprint name plus the underlying error text so the Dockerfile or API failure can be diagnosed.

Source

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

            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,
            dockerfile=dockerfile,
        )
    except Exception as create_err:
        msg = f"Failed to build blueprint '{blueprint_name}': {create_err}"
        raise RuntimeError(msg) from create_err


class RunloopProvider:
    """Create or attach Runloop devboxes, optionally from named blueprints."""

    def __init__(
        self,
        *,
        api_key: str,
        resolve_env_var: Callable[[str], str | None] | None = None,
    ) -> None:
        """Initialize the provider.

        Args:
            api_key: Runloop API bearer token.
            resolve_env_var: Optional env lookup (e.g. for `DEEPAGENTS_CODE_`
                overrides). Defaults to prefix-aware `os.environ` reads.
        """

View on GitHub (pinned to a1af029e6e)

Solutions

1. Read the chained cause (`__cause__`) or the embedded `{create_err}` text to see the actual build/API failure.
2. Test the Dockerfile locally (docker build) and pass a corrected one via `blueprint_dockerfile=`.
3. Retry if the cause is a transient API error (connection/timeout/429).
4. Or skip auto-build by booting with `RUNLOOP_SANDBOX_BLUEPRINT_ID` for a pre-existing blueprint.
5. Fall back to `provider.get_or_create()` with no snapshot to get an empty devbox.

Example fix

// before
provider.get_or_create(snapshot="my-bp", blueprint_dockerfile=bad_dockerfile)

// after
try:
    provider.get_or_create(snapshot="my-bp", blueprint_dockerfile=dockerfile)
except RuntimeError as e:
    print("build failed:", e.__cause__)
    dockerfile = open("Dockerfile").read()  # verified Dockerfile
    provider.get_or_create(snapshot="my-bp", blueprint_dockerfile=dockerfile)

import subprocess

def dockerfile_builds_locally(path: str) -> bool:
    return subprocess.run(
        ["docker", "build", "-q", "-f", path, "."],
        check=False,
    ).returncode == 0

try:
    provider.get_or_create(snapshot="my-bp", blueprint_dockerfile=dockerfile)
except RuntimeError as e:
    cause = e.__cause__
    log.error("blueprint build failed for 'my-bp': %s", cause)

When it happens

Trigger: `get_or_create` is called with `snapshot=<name>` (or `RUNLOOP_SANDBOX_BLUEPRINT_NAME`) for a blueprint name that does not exist, so `_ensure_blueprint` attempts to create it, and the create-or-build call raises (invalid Dockerfile, build error, API error, build timeout).

Common situations: A broken or unsupported Dockerfile passed via `blueprint_dockerfile=`; the default `FROM python:3` Dockerfile failing on the builder; Runloop API outage or rate limit during build; build exceeds the awaited time limit.

Related errors

• Blueprint '{blueprint_name}' exists but its last build faile
• Failed to list blueprints: {e}
• Blueprint name is required when no blueprint ID is set
• {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/fe8426e5fc32e23c. Report an issue: GitHub.