{"record":{"id":"fe8426e5fc32e23c","repo":"langchain-ai/deepagents","slug":"failed-to-build-blueprint-blueprint-name-cre","errorCode":null,"errorMessage":"Failed to build blueprint '{blueprint_name}': {create_err}","messagePattern":"Failed to build blueprint '(.+?)': (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"libs/partners/runloop/langchain_runloop/provider.py","lineNumber":120,"sourceCode":"            if blueprint.status == \"build_complete\":\n                return\n            non_ready_status = blueprint.status\n\n        if not page.has_more or not page.blueprints:\n            break\n        starting_after = page.blueprints[-1].id\n\n    if non_ready_status is not None:\n        raise RuntimeError(_not_ready_message(blueprint_name, non_ready_status))\n\n    try:\n        client.blueprints.create_and_await_build_complete(\n            name=blueprint_name,\n            dockerfile=dockerfile,\n        )\n    except Exception as create_err:\n        msg = f\"Failed to build blueprint '{blueprint_name}': {create_err}\"\n        raise RuntimeError(msg) from create_err\n\n\nclass RunloopProvider:\n    \"\"\"Create or attach Runloop devboxes, optionally from named blueprints.\"\"\"\n\n    def __init__(\n        self,\n        *,\n        api_key: str,\n        resolve_env_var: Callable[[str], str | None] | None = None,\n    ) -> None:\n        \"\"\"Initialize the provider.\n\n        Args:\n            api_key: Runloop API bearer token.\n            resolve_env_var: Optional env lookup (e.g. for `DEEPAGENTS_CODE_`\n                overrides). Defaults to prefix-aware `os.environ` reads.\n        \"\"\"","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/partners/runloop/langchain_runloop/provider.py#L102-L138","documentation":"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.","triggerScenarios":"`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).","commonSituations":"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.","solutions":["Read the chained cause (`__cause__`) or the embedded `{create_err}` text to see the actual build/API failure.","Test the Dockerfile locally (docker build) and pass a corrected one via `blueprint_dockerfile=`.","Retry if the cause is a transient API error (connection/timeout/429).","Or skip auto-build by booting with `RUNLOOP_SANDBOX_BLUEPRINT_ID` for a pre-existing blueprint.","Fall back to `provider.get_or_create()` with no snapshot to get an empty devbox."],"exampleFix":"// before\nprovider.get_or_create(snapshot=\"my-bp\", blueprint_dockerfile=bad_dockerfile)\n\n// after\ntry:\n    provider.get_or_create(snapshot=\"my-bp\", blueprint_dockerfile=dockerfile)\nexcept RuntimeError as e:\n    print(\"build failed:\", e.__cause__)\n    dockerfile = open(\"Dockerfile\").read()  # verified Dockerfile\n    provider.get_or_create(snapshot=\"my-bp\", blueprint_dockerfile=dockerfile)","handlingStrategy":"try-catch","validationCode":"import subprocess\n\ndef dockerfile_builds_locally(path: str) -> bool:\n    return subprocess.run(\n        [\"docker\", \"build\", \"-q\", \"-f\", path, \".\"],\n        check=False,\n    ).returncode == 0","typeGuard":null,"tryCatchPattern":"try:\n    provider.get_or_create(snapshot=\"my-bp\", blueprint_dockerfile=dockerfile)\nexcept RuntimeError as e:\n    cause = e.__cause__\n    log.error(\"blueprint build failed for 'my-bp': %s\", cause)","preventionTips":["Validate the Dockerfile with a local `docker build` before submitting it as a blueprint.","Keep blueprint Dockerfiles pinned to specific base image tags to avoid upstream breakage.","Log `e.__cause__` — the SDK exception carries the real build/API failure.","Retry on transient API errors; fail permanently on Dockerfile errors."],"tags":["runloop","blueprint","dockerfile","build-failed"],"backgroundTag":"docker-build-failed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}