langchain-ai/deepagents · error · ValueError

Unknown sandbox provider: {name}

Error message

Unknown sandbox provider: {name}

What it means

`SandboxRegistry.provider_metadata` raises `ValueError` when no sandbox provider with the requested name is registered. The registry first tries to instantiate the provider (falling back to default metadata if instantiation fails), but if `get_metadata(name)` returns `None` the name is simply not a known provider, so the lookup fails fast.

Source

Thrown at libs/code/deepagents_code/integrations/sandbox_registry.py:330

            ValueError: If `name` is unknown.
        """
        if name in self._config.providers or (
            name in BUILTIN_METADATA and name not in self._entry_points
        ):
            meta = self.get_metadata(name)
            if meta is not None:
                return meta
        if name in self._entry_points:
            try:
                provider = self.create_provider(name)
            except Exception:  # noqa: BLE001  # Metadata probe must not crash discovery
                logger.debug("Could not instantiate provider %r for metadata", name)
                return SandboxProviderMetadata(name=name, working_dir="/workspace")
            return _provider_metadata(provider, name)
        meta = self.get_metadata(name)
        if meta is None:
            msg = f"Unknown sandbox provider: {name}"
            raise ValueError(msg)
        return meta


def _create_builtin_provider(name: str) -> SandboxProvider:
    """Instantiate a built-in provider class (lazy import avoids cycles).

    Returns:
        The built-in `SandboxProvider` instance for `name`.
    """
    from deepagents_code.integrations import sandbox_factory

    builders = {
        "agentcore": sandbox_factory._AgentCoreProvider,
        "daytona": sandbox_factory._DaytonaProvider,
        "langsmith": sandbox_factory._LangSmithProvider,
        "modal": sandbox_factory._ModalProvider,
        "runloop": sandbox_factory._RunloopProvider,
        "vercel": sandbox_factory._VercelProvider,

View on GitHub (pinned to a1af029e6e)

Solutions

1. Check the exact provider name with the registry's list of known providers (e.g. iterate `get_metadata` over registered names or run the CLI's sandbox listing) and correct the spelling
2. Install the package that declares the provider via its entry point (`pip install <provider-plugin>`) into the active environment
3. If implementing a custom provider, verify the entry point is declared in pyproject/packaging metadata under the correct group and reinstall so metadata is regenerated

Example fix

// before
meta = registry.provider_metadata("local-sandbox")
// after
if registry.get_metadata("local-sandbox") is None:
    name = "local"  # corrected provider name
meta = registry.provider_metadata(name)

from deepagents_code.integrations.sandbox_registry import sandbox_registry

def provider_exists(name: str) -> bool:
    return sandbox_registry.get_metadata(name) is not None

if not provider_exists("local"):
    raise SystemExit(f"sandbox provider {name!r} not installed")

def is_known_provider(name: str) -> bool:
    return isinstance(name, str) and sandbox_registry.get_metadata(name) is not None

try:
    meta = registry.provider_metadata(name)
except ValueError as exc:
    logger.error("unknown sandbox provider %r: %s", name, exc)
    available = registry.available_providers()  # or equivalent listing
    raise SystemExit(f"choose one of: {', '.join(available)}")

When it happens

Trigger: Calling `provider_metadata(name)` (directly or via `get_metadata`) with a name that is not a built-in provider and not registered via an entry point — e.g. a typo like `provider_metadata('local-sandbox')` instead of `'local'`, or a plugin provider whose entry point group is missing from the installed distribution.

Common situations: Typos in `--sandbox <name>` values or config; a third-party sandbox plugin not installed in the current environment (wrong venv); an entry-point package installed under an old version that no longer declares the provider.

Related errors

• enable_interpreter=True is not supported with a remote sandb
• Unknown sandbox provider: {name}. Available providers: {', '
• {what} must be absolute: {path}
• Could not determine the home directory: set $HOME, or set DE
• Home directory is not absolute: {launch_home}. Set $HOME to

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