langchain-ai/deepagents · error · ValueError

Sandbox provider '{name}' config is missing 'class_path'

Error message

Sandbox provider '{name}' config is missing 'class_path'

What it means

`SandboxRegistry.create_provider` looks up a provider in config, entry points, then builtins. If a config entry exists for `name` but lacks a truthy `class_path` key, the registry cannot instantiate it and raises ValueError immediately.

Source

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

        Args:
            name: Provider name.

        Returns:
            A `SandboxProvider` instance. Propagates `ImportError` from
                `_load_class` / `EntryPoint.load` if a config or entry-point
                class cannot be imported.

        Raises:
            ValueError: If `name` is unknown or a config provider omits
                `class_path`.
        """
        config_entry = self._config.providers.get(name)
        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`.

View on GitHub (pinned to a1af029e6e)

Solutions

1. Add the `class_path` key in `module.path:ClassName` format to the provider's config entry.
2. Remove the empty config entry so the registry falls back to entry points/builtins.
3. Validate the config structure at startup before handing it to the registry.

Example fix

# before
providers:
  myprov: {}
# after
providers:
  myprov:
    class_path: "mypkg.providers:MyProvider"

def config_entries_valid(config: dict) -> bool:
    return all(
        isinstance(entry, dict) and entry.get('class_path')
        for entry in config.get('providers', {}).values()
    )

try:
    provider = registry.create_provider(name)
except ValueError as exc:
    if "missing 'class_path'" in str(exc):
        raise ConfigError(f"Provider '{name}' needs a class_path in config") from exc
    raise

When it happens

Trigger: A config file (or dict) registering provider `name` as e.g. `{'myp': {}}` or `{'myp': {'class_path': None}}`, then calling `create_provider('myp')` (directly or via `_get_provider`/`provider_metadata`).

Common situations: Hand-editing the sandbox config and omitting `class_path`, a config migration/tool writing empty entries, YAML/JSON nesting mistakes that drop the key.

Related errors

• modes can only be provided when agent is a factory
• models can only be provided when agent is a factory
• -32602
• recursion_limit must be None or a positive integer
• Invalid class_path '{class_path}': must be in module.path:Cl

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