langchain-ai/deepagents · error · RuntimeError

Blueprint name is required when no blueprint ID is set

Error message

Blueprint name is required when no blueprint ID is set

What it means

`RunloopProvider._create_from_blueprint` raises this `RuntimeError` when it is asked to boot from a blueprint but has neither a blueprint ID nor a blueprint name. With the current `get_or_create` flow this is a defensive invariant (a name always resolves from `snapshot` or env before this point), but it documents the internal contract: one of ID or name must be present to create from a blueprint.

Source

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

        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)

    def delete(self, *, sandbox_id: str, **kwargs: Any) -> None:  # noqa: ARG002
        """Shut down a devbox by ID.

        Raises:
            runloop_api_client.NotFoundError: If `sandbox_id` does not refer to
                an existing devbox.
        """
        self._client.devboxes.shutdown(id=sandbox_id)

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass a blueprint name (via `snapshot=` or `RUNLOOP_SANDBOX_BLUEPRINT_NAME`) or a blueprint ID (`RUNLOOP_SANDBOX_BLUEPRINT_ID`).
2. If calling `_create_from_blueprint` directly, always supply `blueprint_name=` when `blueprint_id=` is None.
3. Set `RUNLOOP_SANDBOX_BLUEPRINT_NAME=my-bp` in the environment before creating the provider.
4. If you do not want a blueprint at all, unset both blueprint env vars and pass no `snapshot` so a plain devbox is created.

Example fix

// before
provider._create_from_blueprint(blueprint_id=None, blueprint_name=None, dockerfile=df)  # RuntimeError

// after
devbox = provider._create_from_blueprint(blueprint_id=None, blueprint_name="my-bp", dockerfile=df)

def blueprint_target_ready(blueprint_id: str | None, blueprint_name: str | None) -> bool:
    return blueprint_id is not None or blueprint_name is not None

try:
    devbox = provider._create_from_blueprint(blueprint_id=None, blueprint_name=name, dockerfile=df)
except RuntimeError as e:
    if "Blueprint name is required" in str(e):
        raise ValueError("Set snapshot or RUNLOOP_SANDBOX_BLUEPRINT_NAME") from e
    raise

When it happens

Trigger: `_create_from_blueprint` invoked with `blueprint_id=None` and `blueprint_name=None` — only reachable if the internal resolution logic changes or the method is called directly with both unset (e.g. `RUNLOOP_SANDBOX_BLUEPRINT_ID` set to an empty-but-non-None value is not possible since empty env values resolve to None, but a custom `resolve_env_var` returning a non-empty string for the ID while name lookup fails could shift paths).

Common situations: Direct/subclass calls to `_create_from_blueprint` with neither argument; custom `resolve_env_var` injections that break the ID-or-name invariant; future refactors of `get_or_create`.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Failed to list blueprints: {e}
• Blueprint '{blueprint_name}' exists but its last build faile
• Failed to build blueprint '{blueprint_name}': {create_err}
• Provide exactly one of mode or auto_approve
• a provider already serves rank {provider.rank}

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