microsoft/semantic-kernel · error · VectorStoreInitializationException

Failed to create Azure Cognitive Search client for collectio

Error message

Failed to create Azure Cognitive Search client for collection {collection_name}.

What it means

Raised by _get_search_client when the Azure SearchClient constructor itself throws ValueError. The helper catches ValueError from SearchClient(endpoint, collection_name, credential, **kwargs) and re-wraps it as VectorStoreInitializationException with the collection name, chaining the original as __cause__. The concrete reason is on the cause.

Source

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

    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}).
        token_credential: Optional Token credential (default: {None}).
    """
    if azure_credential:
        return azure_credential

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect the chained cause: except VectorStoreInitializationException as e: print(e.__cause__)
2. Ensure endpoint is a valid https URL (e.g. https://<service>.search.windows.net)
3. Verify the credential matches the endpoint type and that AZURE_AI_SEARCH_API_KEY/credential resolution is correct
4. Update/align the azure-search-documents package version if kwargs are version-specific

Example fix

# before
_get_search_client(endpoint="not-a-url", collection_name="idx", credential=cred)
# raises: Failed to create Azure Cognitive Search client for collection idx.

# after
_get_search_client(
    endpoint="https://mysvc.search.windows.net",
    collection_name="idx",
    credential=cred,
)

from urllib.parse import urlparse

if not urlparse(endpoint).scheme.startswith("http"):
    raise ValueError(f"endpoint must be a valid https URL, got: {endpoint}")
client = _get_search_client(endpoint, collection_name, credential)

from urllib.parse import urlparse


def is_valid_search_endpoint(endpoint: str | None) -> bool:
    if not isinstance(endpoint, str):
        return False
    p = urlparse(endpoint)
    return p.scheme in ("http", "https") and bool(p.netloc)

from semantic_kernel.exceptions import VectorStoreInitializationException

try:
    client = _get_search_client(endpoint, collection_name, credential)
except VectorStoreInitializationException as e:
    cause = e.__cause__
    raise RuntimeError(f"SearchClient construction failed: {cause}") from e

When it happens

Trigger: The azure.search.documents SearchClient rejected its arguments: an invalid endpoint string (not a valid URL), an incompatible credential type for the endpoint, or malformed **kwargs that the client constructor validates.

Common situations: The AZURE_AI_SEARCH_ENDPOINT is malformed or not an https URL; the endpoint is missing the scheme; the credential passed does not match what SearchClient expects (AzureKeyCredential vs token credential mismatch); kwargs contain an unsupported parameter for the installed azure-search-documents version.

Related errors

• Collection name is required to create a search client.
• 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/d7086d2251d661d3. Report an issue: GitHub.