{"record":{"id":"7a649b4b7286e1ba","repo":"langchain-ai/deepagents","slug":"blueprint-name-is-required-when-no-blueprint-id-is","errorCode":null,"errorMessage":"Blueprint name is required when no blueprint ID is set","messagePattern":"Blueprint name is required when no blueprint ID is set","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"libs/partners/runloop/langchain_runloop/provider.py","lineNumber":235,"sourceCode":"        except Exception as e:\n            target = blueprint_name or env_blueprint_id or \"devbox\"\n            msg = f\"Failed to create Runloop devbox from '{target}': {e}\"\n            raise RuntimeError(msg) from e\n\n        return RunloopSandbox(devbox=devbox)\n\n    def _create_from_blueprint(\n        self,\n        *,\n        blueprint_id: str | None,\n        blueprint_name: str | None,\n        dockerfile: str,\n    ) -> Devbox:\n        if blueprint_id is not None:\n            return self._sdk.devbox.create_from_blueprint_id(blueprint_id)\n        if blueprint_name is None:\n            msg = \"Blueprint name is required when no blueprint ID is set\"\n            raise RuntimeError(msg)\n        _ensure_blueprint(self._client, blueprint_name, dockerfile=dockerfile)\n        return self._sdk.devbox.create_from_blueprint_name(blueprint_name)\n\n    def delete(self, *, sandbox_id: str, **kwargs: Any) -> None:  # noqa: ARG002\n        \"\"\"Shut down a devbox by ID.\n\n        Raises:\n            runloop_api_client.NotFoundError: If `sandbox_id` does not refer to\n                an existing devbox.\n        \"\"\"\n        self._client.devboxes.shutdown(id=sandbox_id)\n","sourceCodeStart":217,"sourceCodeEnd":247,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/partners/runloop/langchain_runloop/provider.py#L217-L247","documentation":"`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.","triggerScenarios":"`_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).","commonSituations":"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`.","solutions":["Pass a blueprint name (via `snapshot=` or `RUNLOOP_SANDBOX_BLUEPRINT_NAME`) or a blueprint ID (`RUNLOOP_SANDBOX_BLUEPRINT_ID`).","If calling `_create_from_blueprint` directly, always supply `blueprint_name=` when `blueprint_id=` is None.","Set `RUNLOOP_SANDBOX_BLUEPRINT_NAME=my-bp` in the environment before creating the provider.","If you do not want a blueprint at all, unset both blueprint env vars and pass no `snapshot` so a plain devbox is created."],"exampleFix":"// before\nprovider._create_from_blueprint(blueprint_id=None, blueprint_name=None, dockerfile=df)  # RuntimeError\n\n// after\ndevbox = provider._create_from_blueprint(blueprint_id=None, blueprint_name=\"my-bp\", dockerfile=df)","handlingStrategy":"validation","validationCode":"def blueprint_target_ready(blueprint_id: str | None, blueprint_name: str | None) -> bool:\n    return blueprint_id is not None or blueprint_name is not None","typeGuard":null,"tryCatchPattern":"try:\n    devbox = provider._create_from_blueprint(blueprint_id=None, blueprint_name=name, dockerfile=df)\nexcept RuntimeError as e:\n    if \"Blueprint name is required\" in str(e):\n        raise ValueError(\"Set snapshot or RUNLOOP_SANDBOX_BLUEPRINT_NAME\") from e\n    raise","preventionTips":["Ensure `snapshot` or `RUNLOOP_SANDBOX_BLUEPRINT_NAME` is set whenever blueprint boot is intended.","Don't call the private `_create_from_blueprint` directly; go through `get_or_create`, which resolves name/ID.","If injecting a custom `resolve_env_var`, keep the contract that empty values resolve to `None` and IDs are honored before names.","Treat this as an invariant error: it signals a bug in your resolution logic, not a runtime condition to retry."],"tags":["runloop","blueprint","api-misuse","internal"],"backgroundTag":"missing-required-argument","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}