langchain-ai/deepagents · error · ModelConfigError

Invalid class_path '{class_path}' for provider '{provider}':

Error message

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

What it means

Raised when a custom-model `class_path` configured for a provider lacks the required `module.path:ClassName` separator format. `_create_model_from_class` splits with `rsplit(':', 1)`, so a colon is mandatory; dot-only paths like `mypkg.models.MyModel` cannot be resolved to a module plus attribute.

Source

Thrown at libs/code/deepagents_code/config.py:5378

    Returns:
        Instantiated `BaseChatModel`.

    Raises:
        ModelConfigError: If the class cannot be imported, is not a
            `BaseChatModel` subclass, or fails to instantiate.
    """
    from langchain_core.language_models import (
        BaseChatModel as _BaseChatModel,  # Runtime import; module level is typing only
    )

    from deepagents_code.model_config import ModelConfigError

    if ":" not in class_path:
        msg = (
            f"Invalid class_path '{class_path}' for provider '{provider}': "
            "must be in module.path:ClassName format"
        )
        raise ModelConfigError(msg)

    module_path, class_name = class_path.rsplit(":", 1)

    try:
        module = importlib.import_module(module_path)
    except ImportError as e:
        msg = f"Could not import module '{module_path}' for provider '{provider}': {e}"
        raise ModelConfigError(msg) from e

    cls = getattr(module, class_name, None)
    if cls is None:
        msg = (
            f"Class '{class_name}' not found in module '{module_path}' "
            f"for provider '{provider}'"
        )
        raise ModelConfigError(msg)

    if not (isinstance(cls, type) and issubclass(cls, _BaseChatModel)):

View on GitHub (pinned to a1af029e6e)

Solutions

1. Rewrite the value as `module.path:ClassName`, e.g. `class_path = "my_pkg.models:MyChatModel"`
2. Verify exactly one attribute name follows the colon
3. Ensure the class after the colon is an actual exported symbol

Example fix

// before (config.toml)
[providers.custom]
class_path = "my_pkg.models.MyChatModel"

// after
[providers.custom]
class_path = "my_pkg.models:MyChatModel"

def valid_class_path(class_path: str) -> bool:
    return ":" in class_path and class_path.rsplit(":", 1)[0] and class_path.rsplit(":", 1)[1]

def parse_class_path(class_path: str) -> tuple[str, str] | None:
    if ":" not in class_path:
        return None
    module_path, class_name = class_path.rsplit(":", 1)
    return (module_path, class_name) if module_path and class_name else None

from deepagents_code.model_config import ModelConfigError
try:
    model = create_model(spec, class_path=class_path)
except ModelConfigError as e:
    if "must be in module.path:ClassName format" in str(e):
        class_path = f"{class_path.rsplit('.', 1)[0]}:{class_path.rsplit('.', 1)[1]}"
        model = create_model(spec, class_path=class_path)
    else:
        raise

When it happens

Trigger: A custom model class configured in config.toml (`class_path = "my_pkg.models.MyChatModel"`) is passed to `_create_model_from_class`, and the value contains no `:` character (config.py:5373-5378).

Common situations: Copying a plain dotted Python import path into config instead of the `module:attr` form; dropping the class name entirely; confusing this field with a provider name or a file path.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

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 MCP config at {mcp_config_path}: {exc}

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