langchain-ai/deepagents · error · ValueError

Unknown sandbox provider: {name}. Available providers: {', '

Error message

Unknown sandbox provider: {name}. Available providers: {', '.join(self.available_providers())}

What it means

`SandboxRegistry.create_provider` resolves providers from config, entry points, and builtins. When `name` matches none of these sources, ValueError is raised listing all currently available provider names so the caller can correct the request.

Source

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

        if config_entry is not None:
            class_path = config_entry.get("class_path")
            if not class_path:
                msg = f"Sandbox provider '{name}' config is missing 'class_path'"
                raise ValueError(msg)
            return _load_class(class_path)()

        entry = self._entry_points.get(name)
        if entry is not None:
            return entry.load()()

        if name in BUILTIN_METADATA:
            return _create_builtin_provider(name)

        msg = (
            f"Unknown sandbox provider: {name}. "
            f"Available providers: {', '.join(self.available_providers())}"
        )
        raise ValueError(msg)

    def provider_metadata(self, name: str) -> SandboxProviderMetadata:
        """Return authoritative metadata for `name`.

        Config providers are described statically. Entry-point providers are
        instantiated so capability flags they expose via a `metadata` attribute
        take effect; on failure this falls back to the static placeholder.
        Built-in metadata is used only when no entry point overrides that name.

        Args:
            name: Provider name.

        Returns:
            The provider's metadata.

        Raises:
            ValueError: If `name` is unknown.
        """

View on GitHub (pinned to a1af029e6e)

Solutions

Use one of the names listed in the error's `Available providers:` output.
Install the provider's package so its entry point is discovered (e.g. `pip install <sandbox-package>`).
Register the provider in config with a valid `class_path` or via entry points.
Check for renames if upgrading the library and update the configured name.

Example fix

# before
provider = registry.create_provider('vercel')  # unknown
# after
$ pip install vercel-sandbox  # or use an available name
provider = registry.create_provider('vercel')

Defensive patterns

Strategy: validation

Validate before calling

registry = SandboxRegistry()
if provider_name not in registry.available_providers():
    raise ConfigError(
        f"'{provider_name}' not available; choose from {registry.available_providers()}"
    )

Try / catch

try:
    provider = registry.create_provider(name)
except ValueError as exc:
    print(exc)  # includes 'Available providers: ...'
    name = prompt_user_for_provider(registry.available_providers())

Prevention

Check registry.available_providers() before wiring a provider name
Install the optional package for entry-point providers before use
Grep config for provider names after library upgrades to catch renames

When it happens

Trigger: `create_provider('vercel')` when the Vercel package isn't installed (no entry point registered) or any misspelled/unregistered name passed to `create_provider`, `_get_provider`, or `provider_metadata`.

Common situations: Typos in the sandbox provider setting, using a provider before installing its package (entry point not discovered), provider renamed across library versions, running in an env where optional providers were never registered.

Related errors

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