langchain-ai/deepagents · error · ValueError

Invalid class_path '{class_path}': must be in module.path:Cl

Error message

Invalid class_path '{class_path}': must be in module.path:ClassName format

What it means

`_load_class` resolves a dynamically configured sandbox provider from a `module.path:ClassName` string. A class_path without a `:` separator cannot be split into module and class parts, so a ValueError is raised explaining the required format.

Source

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

def _load_class(class_path: str) -> type:
    """Import a `module.path:ClassName` provider class.

    Args:
        class_path: Fully-qualified class path.

    Returns:
        The imported class object.

    Raises:
        ValueError: If `class_path` is malformed.
        ImportError: If the module cannot be imported or lacks the class.
    """
    if ":" not in class_path:
        msg = (
            f"Invalid class_path '{class_path}': must be in "
            "module.path:ClassName format"
        )
        raise ValueError(msg)
    module_path, class_name = class_path.rsplit(":", 1)
    module = importlib.import_module(module_path)
    cls = getattr(module, class_name, None)
    if cls is None or not isinstance(cls, type):
        msg = f"Class '{class_name}' not found in module '{module_path}'"
        raise ImportError(msg)
    return cls


def _provider_metadata(provider: SandboxProvider, name: str) -> SandboxProviderMetadata:
    """Extract metadata from a provider instance or class.

    Providers may expose a `metadata` attribute/property; otherwise a minimal
    default is synthesized.

    Args:
        provider: Provider instance.
        name: Provider name to use when synthesizing defaults.

View on GitHub (pinned to a1af029e6e)

Solutions

1. Rewrite class_path as `module.path:ClassName`, e.g. `mypackage.providers:MyProvider`.
2. Validate config at load time with a regex like `^[\w.]+:[\w]+$`.
3. Check the provider config documentation for the exact separator.

Example fix

# before
class_path = "mypackage.providers.MyProvider"
# after
class_path = "mypackage.providers:MyProvider"

import re

def is_valid_class_path(class_path: str) -> bool:
    return re.fullmatch(r'[\w.]+:[\w]+', class_path) is not None

try:
    provider = registry.create_provider(name)
except ValueError as exc:
    raise ConfigError(f'Fix sandbox provider config: {exc}') from exc

When it happens

Trigger: Configuring a sandbox provider with `class_path` values like `'mypkg.MyProvider'`, `'MyProvider'`, or a Windows-style path — anything lacking `:`, passed through `create_provider`/`_get_provider`.

Common situations: Typos in config files where `.` was used instead of `:`, copying a fully-qualified name from an IDE that uses dot notation, misunderstanding the documented format.

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
• Class '{class_name}' not found in module '{module_path}'

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