langchain-ai/deepagents · error · ModelConfigError

Invalid model spec '{model_spec}': model name is required (e

Error message

Invalid model spec '{model_spec}': model name is required (e.g., 'anthropic:claude-sonnet-4-5' or 'claude-sonnet-4-5')

What it means

Raised by `create_model` when the model spec contains a colon but no model name — e.g. 'anthropic:' or ':'. ModelSpec parsing rejected it, and since the text after the colon is empty, the app cannot treat it as a bare model name.

Source

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

        provider, model_name = parsed.provider, parsed.model
    elif inferred_provider == "bedrock":
        provider, model_name = inferred_provider, model_spec
    elif parsed:
        # Explicit provider:model (e.g., "anthropic:claude-sonnet-4-5")
        provider, model_name = parsed.provider, parsed.model
    elif ":" in model_spec:
        # Contains colon but ModelSpec rejected it (empty provider or model)
        _, _, after = model_spec.partition(":")
        if after:
            # Leading colon (e.g., ":claude-opus-4-6") — treat as bare model name
            model_name = after
            provider = detect_provider(model_name) or ""
        else:
            msg = (
                f"Invalid model spec '{model_spec}': model name is required "
                "(e.g., 'anthropic:claude-sonnet-4-5' or 'claude-sonnet-4-5')"
            )
            raise ModelConfigError(msg)
    else:
        # Bare model name — auto-detect provider or let init_chat_model infer
        model_name = model_spec
        provider = inferred_provider or ""

    if provider == "google_vertexai" and model_name.lower().startswith("claude-"):
        msg = (
            f"Claude model '{model_name}' uses the Anthropic Messages API on "
            "Vertex AI. Use "
            f"'google_anthropic_vertex:{model_name}' instead of "
            f"'google_vertexai:{model_name}'."
        )
        raise ModelConfigError(msg)

    resolved_spec = f"{provider}:{model_name}" if provider else model_spec
    # The authoritative policy gate, and its position is load-bearing: it runs
    # after provider inference (so a bare name is matched in canonical form)
    # but before credential bridging, provider profiles, and provider imports.

View on GitHub (pinned to a1af029e6e)

Solutions

Supply the model name after the colon: 'anthropic:claude-sonnet-4-5'.
Or drop the colon entirely and use a bare name like 'claude-sonnet-4-5' for auto-detection.
Check the config/env value feeding model_spec for an unset or truncated variable.

Example fix

// before
model = create_model("anthropic:")
// after
model = create_model("anthropic:claude-sonnet-4-5")

Defensive patterns

Strategy: validation

Validate before calling

def is_valid_model_spec(spec: str) -> bool:
    if ":" in spec:
        provider, _, model = spec.partition(":")
        return bool(provider and model)
    return bool(spec)
assert is_valid_model_spec(model_spec), "model name is required after ':'"

Try / catch

try:
    result = create_model(spec)
except ModelConfigError as e:
    if "model name is required" in str(e):
        spec = spec.rstrip(":")  # fall back to bare-name auto-detection
        result = create_model(spec)

Prevention

Never leave the model part of 'provider:' empty in config or env
Expand shell variables feeding model_spec and fail fast if empty
Strip accidental trailing colons before passing specs
Use bare model names when you want auto-detection instead of an empty provider

When it happens

Trigger: Calling `create_model('anthropic:')` or any `provider:` string with an empty model part; also a spec like ':' with nothing on either side.

Common situations: Truncated config.toml value (model key set to 'openai:'), shell variable interpolation that dropped the model name ('$MODEL' unset leaving 'anthropic:'), accidental trailing colon in a slash command.

Related errors

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