microsoft/semantic-kernel · error · ServiceInitializationError

The OpenAI embedding model ID is required.

Error message

The OpenAI embedding model ID is required.

What it means

Raised while constructing an OpenAITextEmbedding service. After OpenAISettings is built (merging the ai_model_id argument with OPENAI_* env vars), if openai_settings.embedding_model_id is still falsy the service cannot generate embeddings and throws ServiceInitializationError. This is a missing-config guard, separate from the settings ValidationError wrapper.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/open_ai_text_embedding.py:65

            default_headers (Mapping[str,str] | None): The default headers mapping of string keys to
                string values for HTTP requests. (Optional)
            async_client (Optional[AsyncOpenAI]): An existing client to use. (Optional)
            env_file_path (str | None): Use the environment settings file as
                a fallback to environment variables. (Optional)
            env_file_encoding (str | None): The encoding of the environment settings file. (Optional)
        """
        try:
            openai_settings = OpenAISettings(
                api_key=api_key,
                org_id=org_id,
                embedding_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 openai_settings.embedding_model_id:
            raise ServiceInitializationError("The OpenAI embedding model ID is required.")
        super().__init__(
            ai_model_id=openai_settings.embedding_model_id,
            api_key=openai_settings.api_key.get_secret_value() if openai_settings.api_key else None,
            ai_model_type=OpenAIModelTypes.EMBEDDING,
            org_id=openai_settings.org_id,
            service_id=service_id,
            default_headers=default_headers,
            client=async_client,
        )

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

        Args:
            settings: A dictionary of settings for the service.
        """
        return cls(

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass ai_model_id explicitly: OpenAITextEmbedding(ai_model_id='text-embedding-3-small', api_key='sk-...')
2. Set the environment variable: export OPENAI_EMBEDDING_MODEL_ID=text-embedding-3-small
3. Add OPENAI_EMBEDDING_MODEL_ID to your .env and pass env_file_path to the constructor
4. Confirm the variable name exactly matches OPENAI_EMBEDDING_MODEL_ID (note: embedding, not embed)

Example fix

# before
service = OpenAITextEmbedding(api_key="sk-...")
# raises ServiceInitializationError: The OpenAI embedding model ID is required.

# after
service = OpenAITextEmbedding(ai_model_id="text-embedding-3-small", api_key="sk-...")

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

s = OpenAISettings()
if not s.embedding_model_id:
    raise ValueError("OPENAI_EMBEDDING_MODEL_ID is required before building OpenAITextEmbedding")

import os


def has_embedding_model(ai_model_id: str | None) -> bool:
    return bool(ai_model_id or os.getenv("OPENAI_EMBEDDING_MODEL_ID"))

from semantic_kernel.exceptions.service_exceptions import ServiceInitializationError

try:
    service = OpenAITextEmbedding()
except ServiceInitializationError as e:
    if "embedding model ID is required" in str(e):
        raise SystemExit("Set OPENAI_EMBEDDING_MODEL_ID or pass ai_model_id") from e
    raise

When it happens

Trigger: Calling OpenAITextEmbedding() with no ai_model_id argument AND no OPENAI_EMBEDDING_MODEL_ID environment variable. The constructor only falls through to this error when both sources are empty.

Common situations: OPENAI_EMBEDDING_MODEL_ID is unset in production/CI; the .env file is not loaded because env_file_path is wrong or missing; the developer set OPENAI_CHAT_MODEL_ID but not the embedding variable; switching from ada-002 to text-embedding-3-small and forgetting to update the env var name.

Related errors

• The OpenAI text model ID is required.
• The OpenAI text to audio model ID is required.
• The OpenAI text to image model ID is required.
• The vector store must have an embedding generator.
• Failed to initialize the Amazon Bedrock Text Embedding Servi

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