langchain-ai/deepagents · error · ModelConfigError

Failed to initialize model '{spec}': {e}

Error message

Failed to initialize model '{spec}': {e}

What it means

Raised when model construction fails with an unexpected exception attributed to provider SDK auth or network errors. Unlike the ValueError/TypeError branch, this is a catch-all: the provider and model were valid, but instantiating the SDK client failed.

Source

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

                    f"{install_hint}, then retry with `/model`."
                )
            raise MissingProviderPackageError(
                msg, provider=provider, package=package
            ) from e
        raise ModelConfigError(msg) from e
    except (ValueError, TypeError) as e:
        if not provider:
            # Both app auto-detection and `init_chat_model`'s own inference
            # failed; surface a structured error so the UI can render the
            # docs URL as a clickable link.
            raise UnknownProviderError(model_spec=model_name) from e
        spec = f"{provider}:{model_name}"
        msg = f"Invalid model configuration for '{spec}': {e}"
        raise ModelConfigError(msg) from e
    except Exception as e:  # provider SDK auth/network errors
        spec = f"{provider}:{model_name}" if provider else model_name
        msg = f"Failed to initialize model '{spec}': {e}"
        raise ModelConfigError(msg) from e


@dataclass(frozen=True)
class ModelResult:
    """Result of creating a chat model, bundling the model with its metadata.

    This separates model creation from runtime-state mutation so callers can
    decide when to commit the metadata to process-wide state.

    Attributes:
        model: The instantiated chat model.
        model_name: Resolved model name.
        provider: Resolved provider name.
        context_limit: Max input tokens from the model profile, or `None`.
        unsupported_modalities: Input modalities not indicated as supported by
            the model profile (e.g. `{"audio", "video"}`).
        model_retries: Effective model-node retry count for the resolved
            provider (see `_resolve_model_retries_from_section`). `0` disables

View on GitHub (pinned to a1af029e6e)

Solutions

1. Check credentials: run `/auth` or verify the provider's API key env var is set and valid.
2. Verify any custom base URL (e.g. OPENAI_BASE_URL) is reachable.
3. Read the chained exception for the SDK's specific message (auth vs network).
4. Reinstall/upgrade the provider package if the SDK itself is failing to import or initialize.

Example fix

// before
export ANTHROPIC_API_KEY=sk-expired-key
// after
export ANTHROPIC_API_KEY=sk-ant-valid-current-key

import os
assert os.environ.get("ANTHROPIC_API_KEY"), "missing API key before create_model()"

try:
    result = create_model(spec)
except ModelConfigError as e:
    cause = e.__cause__
    if cause and "auth" in str(cause).lower():
        prompt_reauth()  # e.g. run /auth
    else:
        schedule_retry_with_backoff()

When it happens

Trigger: `create_model('provider:model')` where the provider SDK raises during initialization — expired/invalid API key rejected at client construction, unreachable base URL, corrupted SDK install, or any non-ValueError/TypeError exception.

Common situations: Rotated or missing API keys, ANTHROPIC_BASE_URL/OPENAI_BASE_URL pointing to a dead proxy, corporate firewall blocking the endpoint, SDK version incompatibilities.

Related errors

• Failed to parse credential file {path}: {exc}. Delete the fi
• Credential file {path} is not a JSON object. Delete it and r
• Credential file {path} has unsupported version {version!r} (
• Failed to write credential file {auth_path()}: {exc}. Check
• Provider name cannot be empty

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