microsoft/autogen · critical · ValueError

model is required for OpenAIChatCompletionClient

Error message

model is required for OpenAIChatCompletionClient

What it means

Thrown by the OpenAIChatCompletionClient constructor when the kwargs do not include a 'model' key. The model identifier is mandatory for capability resolution, token counting, and request construction, and it also serves as the component-serialization key, so the constructor fails fast without it.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py:1443

            config = {
                "provider": "OpenAIChatCompletionClient",
                "config": {"model": "gpt-4o", "api_key": "REPLACE_WITH_YOUR_API_KEY"},
            }

            client = ChatCompletionClient.load_component(config)

        To view the full list of available configuration options, see the :py:class:`OpenAIClientConfigurationConfigModel` class.

    """

    component_type = "model"
    component_config_schema = OpenAIClientConfigurationConfigModel
    component_provider_override = "autogen_ext.models.openai.OpenAIChatCompletionClient"

    def __init__(self, **kwargs: Unpack[OpenAIClientConfiguration]):
        if "model" not in kwargs:
            raise ValueError("model is required for OpenAIChatCompletionClient")

        model_capabilities: Optional[ModelCapabilities] = None  # type: ignore
        self._raw_config: Dict[str, Any] = dict(kwargs).copy()
        copied_args = dict(kwargs).copy()

        if "model_capabilities" in kwargs:
            model_capabilities = kwargs["model_capabilities"]
            del copied_args["model_capabilities"]

        model_info: Optional[ModelInfo] = None
        if "model_info" in kwargs:
            model_info = kwargs["model_info"]
            del copied_args["model_info"]

        add_name_prefixes: bool = False
        if "add_name_prefixes" in kwargs:
            add_name_prefixes = kwargs["add_name_prefixes"]

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Pass model="..." explicitly to the constructor
2. Check for misspelled keys such as model_name or deployment_name being used instead of model
3. For Azure, pass model (the deployment's underlying model name) alongside azure_deployment
4. Validate config dicts contain 'model' before component_config loading

Example fix

# before
client = OpenAIChatCompletionClient(api_key=KEY)  # ValueError

# after
client = OpenAIChatCompletionClient(model="gpt-4o-2024-08-06", api_key=KEY)

config = {"api_key": KEY, ...}
if "model" not in config:
    raise KeyError("client config missing required 'model' key")
client = OpenAIChatCompletionClient(**config)

def is_valid_client_config(config: dict) -> bool:
    return isinstance(config, dict) and isinstance(config.get("model"), str) and bool(config["model"])

try:
    client = OpenAIChatCompletionClient(**config)
except ValueError as e:
    if "model is required" in str(e):
        raise ConfigError(f"missing 'model' in client config: {sorted(config)}") from e
    raise

When it happens

Trigger: Constructing OpenAIChatCompletionClient() with no arguments, or with only api_key/azure settings and no model; deserializing a component config whose dict lacks 'model'; typos like model_name= instead of model=.

Common situations: Loading client config from a dict/YAML where the model key was omitted or misspelled; Azure setups where users assume azure_deployment replaces model; programmatic config assembly that conditionally sets model and skips it.

Related errors

• Unsupported config type {config.GetType()}
• Please set OPENAI_API_KEY environment variable.
• Please set OPENAI_API_KEY environment variable.
• Please set OPENAI_API_KEY environment variable.
• Please set OPENAI_API_KEY environment variable.

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/ce92963d600199b4. Report an issue: GitHub.