microsoft/semantic-kernel · error · VectorStoreInitializationException

Collection name is required to create a search client.

Error message

Collection name is required to create a search client.

What it means

Raised by the Azure AI Search helper _get_search_client when collection_name is falsy. The function requires a concrete collection (index) name to construct a SearchClient; if collection_name is None or an empty string it throws VectorStoreInitializationException (subclass of VectorStoreException, not ServiceException).

Source

Thrown at python/semantic_kernel/connectors/azure_ai_search.py:159

    - index_name: str - Azure AI Search index name (Env var AZURE_AI_SEARCH_INDEX_NAME)
    """

    env_prefix: ClassVar[str] = "AZURE_AI_SEARCH_"

    api_key: SecretStr | None = None
    endpoint: HttpsUrl
    index_name: str | None = None


def _get_search_client(
    endpoint: str,
    collection_name: str | None,
    credential: "AzureKeyCredential | AsyncTokenCredential",
    **kwargs: Any,
) -> SearchClient:
    """Create a search client for a collection."""
    if not collection_name:
        raise VectorStoreInitializationException("Collection name is required to create a search client.")
    try:
        return SearchClient(endpoint, collection_name, credential, **kwargs)
    except ValueError as exc:
        raise VectorStoreInitializationException(
            f"Failed to create Azure Cognitive Search client for collection {collection_name}."
        ) from exc


def _resolve_credential(
    azure_ai_search_settings: AzureAISearchSettings,
    azure_credential: AzureKeyCredential | None = None,
    token_credential: "AsyncTokenCredential | None" = None,
) -> "AzureKeyCredential | AsyncTokenCredential":
    """Resolve the credential to use for Azure AI Search.

    Args:
        azure_ai_search_settings: Azure AI Search settings.
        azure_credential: Optional Azure credentials (default: {None}).

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass an explicit collection name: AzureAISearchCollection(collection_name='my-index', ...)
2. Set the AZURE_AI_SEARCH_INDEX_NAME environment variable
3. If inferring from a model, ensure the model class defines a collection name attribute used by _get_collection_name_from_model

Example fix

# before
collection = AzureAISearchCollection(
    collection_name=None, settings=settings
)

# after
collection = AzureAISearchCollection(
    collection_name="my-docs-index", settings=settings
)

if not collection_name:
    raise ValueError("collection_name is required for an Azure AI Search client")
client = _get_search_client(endpoint, collection_name, credential)

def is_valid_collection_name(name: str | None) -> bool:
    return isinstance(name, str) and name.strip() != ""

from semantic_kernel.exceptions import VectorStoreInitializationException

try:
    collection = AzureAISearchCollection(collection_name=name, settings=settings)
except VectorStoreInitializationException as e:
    if "Collection name is required" in str(e):
        raise ValueError("Provide a non-empty collection_name") from e
    raise

When it happens

Trigger: Calling _get_search_client (directly, or via AzureAISearchCollection which passes collection_name) with collection_name=None or ''. This happens when a collection was created without a name or the name resolved from a model/definition was empty.

Common situations: Creating an AzureAISearchCollection without specifying collection_name and the inferred name (from _get_collection_name_from_model) returned None; the AZURE_AI_SEARCH_INDEX_NAME env var is unset and no explicit name was passed; a record model without a __kernel_collection_name__ attribute.

Related errors

• Failed to create Azure Cognitive Search client for collectio
• The vector store must have an embedding generator.
• Please provide a token endpoint to retrieve the authenticati
• Please provide a credential to retrieve the authentication t
• AI Chat Service type '{appConfig.RagConfig.AIChatService}' i

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