langchain-ai/deepagents · error · ModelConfigError

Failed to instantiate '{class_path}' for '{provider}:{model_

Error message

Failed to instantiate '{class_path}' for '{provider}:{model_name}': {e}

What it means

Raised when a validated BaseChatModel subclass from `class_path` throws any exception in its constructor. The loader calls `cls(model=model_name, **kwargs)` and wraps any failure as `ModelConfigError` chained to the original exception, naming the class path and `provider:model` spec so constructor failures surface uniformly.

Source

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

    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)):
        msg = (
            f"'{class_path}' is not a BaseChatModel subclass (got {type(cls).__name__})"
        )
        raise ModelConfigError(msg)

    try:
        return cls(model=model_name, **kwargs)
    except Exception as e:
        msg = f"Failed to instantiate '{class_path}' for '{provider}:{model_name}': {e}"
        raise ModelConfigError(msg) from e


def _create_model_via_init(
    model_name: str,
    provider: str,
    kwargs: dict[str, Any],
) -> BaseChatModel:
    """Create a model using langchain's `init_chat_model`.

    Args:
        model_name: Model identifier.
        provider: Provider name (may be empty for auto-detection).
        kwargs: Additional keyword arguments.

    Returns:
        Instantiated `BaseChatModel`.

    Raises:

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Read the chained original exception at the end of the traceback — it names the real constructor failure
  2. Fix the offending kwarg in `[providers.<p>.params]` (or per-model params) in config.toml
  3. Supply the missing credential/env var the custom class expects and retry

Example fix

// before (config.toml)
[providers.custom.params]
max_retries = "3"  # constructor expects int

// after
[providers.custom.params]
max_retries = 3
Defensive patterns

Strategy: try-catch

Validate before calling

import inspect
def kwargs_accepted(cls: type, kwargs: dict) -> list[str]:
    params = inspect.signature(cls.__init__).parameters
    return [k for k in kwargs if k not in params and k != "model"]

Try / catch

from deepagents_code.model_config import ModelConfigError
try:
    model = create_model(spec, class_path=class_path)
except ModelConfigError as e:
    logger.error("Custom model init failed for %s: %s", spec, e.__cause__)
    raise SystemExit(1)  # inspect e.__cause__ for the real constructor error

Prevention

When it happens

Trigger: `_create_model_from_class` instantiates the class and `__init__` raises — wrong model name, eagerly-validated missing API key, an unsupported kwarg from config params, or an init-time network call failing (config.py:5402-5406).

Common situations: Config params passing kwargs the constructor does not accept; custom class validating its API key at init while the env var is absent; a mistyped model name forwarded as `model=`.

Related errors

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