langchain-ai/deepagents · error · KeyError

{sandbox_id}

Error message

{sandbox_id}

What it means

When `get_or_create` is given a `sandbox_id` that Runloop does not recognize, the provider catches the SDK's `NotFoundError` and re-raises it as a plain `KeyError(sandbox_id)`. The KeyError is a stable, dependency-free signal that the devbox does not exist (or is not accessible with the current credentials), so callers can detect a missing sandbox without importing `runloop_api_client`.

Source

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

            KeyError: If `sandbox_id` does not refer to an existing devbox
                (the SDK's `NotFoundError` is translated to `KeyError` so
                callers can map a missing sandbox without importing the SDK).
            RuntimeError: If devbox or blueprint creation fails.
        """
        if kwargs:
            msg = f"Received unsupported arguments: {list(kwargs.keys())}"
            raise TypeError(msg)

        dockerfile = blueprint_dockerfile or _DEFAULT_BLUEPRINT_DOCKERFILE

        if sandbox_id is not None:
            try:
                devbox = self._sdk.devbox.from_id(sandbox_id)
            except NotFoundError as e:
                # Translate the SDK's not-found error into a stable KeyError so
                # callers (e.g. the deepagents-code factory) can detect a
                # missing sandbox without importing runloop_api_client.
                raise KeyError(sandbox_id) from e
            return RunloopSandbox(devbox=devbox)

        env_blueprint_id = self._resolve_env("RUNLOOP_SANDBOX_BLUEPRINT_ID")
        env_blueprint_name = self._resolve_env("RUNLOOP_SANDBOX_BLUEPRINT_NAME")
        blueprint_name = snapshot or env_blueprint_name
        use_blueprint = env_blueprint_id is not None or blueprint_name is not None

        try:
            if use_blueprint:
                devbox = self._create_from_blueprint(
                    blueprint_id=env_blueprint_id,
                    blueprint_name=blueprint_name,
                    dockerfile=dockerfile,
                )
            else:
                devbox = self._sdk.devbox.create()
        except (AuthenticationError, PermissionDeniedError) as e:
            msg = (

View on GitHub (pinned to a1af029e6e)

Solutions

1. Check the KeyError value: the sandbox ID is the message — verify it against your records.
2. Call `get_or_create()` with no `sandbox_id` to create a fresh devbox instead.
3. Verify the ID against the Runloop dashboard and confirm you are using the same API key/account that owns the devbox.
4. Wrap the call in try/except KeyError and implement create-on-missing logic.
5. List current devboxes via the SDK to find the correct ID.

Example fix

// before
code = provider.get_or_create(sandbox_id="dbx_abc")

// after
try:
    code = provider.get_or_create(sandbox_id=saved_id)
except KeyError:
    code = provider.get_or_create()  # devbox gone; create a new one

def sandbox_id_looks_valid(sandbox_id: str) -> bool:
    return bool(sandbox_id) and sandbox_id.startswith("dbx_")

def is_existing_sandbox_result(result: object) -> bool:
    return not isinstance(result, KeyError)

try:
    sandbox = provider.get_or_create(sandbox_id=saved_id)
except KeyError as e:
    log.warning("devbox %s no longer exists; creating a new one", e.args[0])
    sandbox = provider.get_or_create()

When it happens

Trigger: Calling `provider.get_or_create(sandbox_id="...")` where the ID was already deleted (devboxes are ephemeral), never existed, was mistyped/truncated, or belongs to a different Runloop account/project.

Common situations: Reattaching to a devbox ID persisted from a previous session after it was shut down; copy-paste errors in the ID; using an ID from a different API key's workspace.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Thread not found: {value}
• Couldn't find an MCP server named '{server_name}', expected
• Error: Skill '{skill_name}' not found.
• Failed to list blueprints: {e}
• Blueprint '{blueprint_name}' exists but its last build faile

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