langchain-ai/deepagents · error · ImportError

Class '{class_name}' not found in module '{module_path}'

Error message

Class '{class_name}' not found in module '{module_path}'

What it means

`_load_class` imports the module portion of a class_path and then looks up the class attribute. If the attribute is missing or is not a type (e.g. it's a function or instance), an ImportError is raised naming the class and module, indicating the resolved entry point doesn't point at a class.

Source

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

    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.

    Returns:
        The provider's metadata.
    """
    meta = getattr(provider, "metadata", None)
    if isinstance(meta, SandboxProviderMetadata):

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Verify the class name exists in the module: `python -c "import mypkg.providers; print(mypkg.providers.MyProvider)"`.
  2. Correct the class name spelling in the `class_path` config value.
  3. If the entry is a factory function, export a class or wrap it so the class_path points to a `type`.

Example fix

# before
class_path = "mypkg.providers:SandbxProvider"  # typo
# after
class_path = "mypkg.providers:SandboxProvider"
Defensive patterns

Strategy: validation

Validate before calling

import importlib

def class_path_resolves(class_path: str) -> bool:
    module_path, cls_name = class_path.rsplit(':', 1)
    mod = importlib.import_module(module_path)
    obj = getattr(mod, cls_name, None)
    return isinstance(obj, type)

Type guard

def is_provider_class(obj: object) -> bool:
    return isinstance(obj, type)

Try / catch

try:
    provider = registry.create_provider(name)
except ImportError as exc:
    raise ConfigError(f'class_path points to a missing/non-class symbol: {exc}') from exc

Prevention

When it happens

Trigger: `create_provider('myprov')` where the config's class_path names a class that doesn't exist in the module (`mypkg.providers:MyProvier` typo), or where the symbol is not a class (a factory function, constant, or lazily-imported name).

Common situations: Renaming or deleting a provider class without updating config, typos in the class name, pointing at a `create_provider()` factory function instead of the class itself, circular imports leaving the attribute unset.

Related errors

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