microsoft/semantic-kernel · critical · ServiceInitializationError

The OpenAI model ID is required.

Error message

The OpenAI model ID is required.

What it means

Raised during OpenAIChatCompletion construction when the resolved OpenAISettings object has a falsy chat_model_id. The service builds its settings from constructor args, .env file, and environment variables (in that precedence), then refuses to start without a model name because every downstream request requires it.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/open_ai_chat_completion.py:67

                to environment variables. (Optional)
            env_file_encoding (str | None): The encoding of the environment settings file. (Optional)
            instruction_role (str | None): The role to use for 'instruction' messages, for example,
        """
        try:
            openai_settings = OpenAISettings(
                api_key=api_key,
                org_id=org_id,
                chat_model_id=ai_model_id,
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
            )
        except ValidationError as ex:
            raise ServiceInitializationError("Failed to create OpenAI settings.", ex) from ex

        if not async_client and not openai_settings.api_key:
            raise ServiceInitializationError("The OpenAI API key is required.")
        if not openai_settings.chat_model_id:
            raise ServiceInitializationError("The OpenAI model ID is required.")

        super().__init__(
            ai_model_id=openai_settings.chat_model_id,
            api_key=openai_settings.api_key.get_secret_value() if openai_settings.api_key else None,
            org_id=openai_settings.org_id,
            service_id=service_id,
            ai_model_type=OpenAIModelTypes.CHAT,
            default_headers=default_headers,
            client=async_client,
            instruction_role=instruction_role,
        )

    @classmethod
    def from_dict(cls, settings: dict[str, Any]) -> "OpenAIChatCompletion":
        """Initialize an Open AI service from a dictionary of settings.

        Args:
            settings: A dictionary of settings for the service.

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set the OPENAI_CHAT_MODEL_ID environment variable (or add it to your .env file), e.g. OPENAI_CHAT_MODEL_ID=gpt-4o
2. Pass ai_model_id explicitly to the constructor: OpenAIChatCompletion(api_key=..., ai_model_id='gpt-4o')
3. Verify your .env file path and encoding match the env_file_path / env_file_encoding arguments if you are loading from a custom location

Example fix

# before
service = OpenAIChatCompletion(api_key=os.environ['OPENAI_API_KEY'])
# after
service = OpenAIChatCompletion(
    api_key=os.environ['OPENAI_API_KEY'],
    ai_model_id='gpt-4o',
)

import os
from semantic_kernel.connectors.ai.open_ai import OpenAISettings

settings = OpenAISettings()
if not settings.chat_model_id:
    raise ValueError('OPENAI_CHAT_MODEL_ID is not set. Configure it in .env or pass ai_model_id.')

from semantic_kernel.exceptions.service_exceptions import ServiceInitializationError

try:
    service = OpenAIChatCompletion(api_key=key)
except ServiceInitializationError as e:
    if 'model ID is required' in str(e):
        # load model from alternate source and retry
        ...

When it happens

Trigger: Instantiating OpenAIChatCompletionBase (or AzureOpenAIChatCompletion) without passing ai_model_id AND without setting OPENAI_CHAT_MODEL_ID / the .env equivalent. The ai_model_id constructor arg is None, env var is unset, and .env file is absent or does not contain a chat model id.

Common situations: Forgetting to set OPENAI_CHAT_MODEL_ID in .env after cloning a repo; renaming the env var during a config refactor; deploying to a new environment without copying .env; passing only api_key but not the model name in code.

Related errors

• Failed to get a response from the chat completion service.
• Ollama chat model ID is required.
• The OpenAI realtime model ID is required.
• The OpenAI text model ID is required.
• OPENAI_API_KEY is not set.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/ed3867d4282423be. Report an issue: GitHub.