What causes "Failed to search the collection." in microsoft/semantic-kernel?

Inspect exc.__cause__ for the actual azure.core exception and its status_code to determine the real failure.

microsoft/semantic-kernel · error · VectorSearchExecutionException

Failed to search the collection.

Error message

Failed to search the collection.

What it means

Raised by _inner_search when the underlying await self.search_client.search(**search_args, **kwargs) raises any Exception. The connector wraps every failure — network, auth, throttling, bad query syntax, missing index — into a VectorSearchExecutionException with this generic message, chaining the original via 'from exc'. The real cause is on exc.__cause__.

Source

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

                vector = await self._generate_vector_from_values(values, options) if vector is None else vector
                if vector is not None:
                    search_args["vector_queries"] = [
                        VectorizedQuery(
                            vector=vector,  # type: ignore
                            fields=vector_field.name if vector_field else None,
                        )
                    ]
                else:
                    search_args["vector_queries"] = [
                        VectorizableTextQuery(
                            text=values,
                            fields=vector_field.name if vector_field else None,
                        )
                    ]
        try:
            raw_results = await self.search_client.search(**search_args, **kwargs)
        except Exception as exc:
            raise VectorSearchExecutionException("Failed to search the collection.") from exc
        return KernelSearchResults(
            results=self._get_vector_search_results_from_results(raw_results, options),
            total_count=await raw_results.get_count() if options.include_total_count else None,
        )

    @override
    def _lambda_parser(self, node: ast.AST) -> Any:
        def _parse_attribute_chain(attr_node: ast.Attribute) -> str:
            parts = []
            current = attr_node
            while isinstance(current, ast.Attribute):
                parts.append(current.attr)
                current = current.value  # type: ignore
            if isinstance(current, ast.Name):
                # skip the root variable name (e.g., 'x')
                pass
            else:
                raise NotImplementedError(f"Unsupported attribute chain root: {type(current)}")

View on GitHub (pinned to c028a0c7dc)

Solutions

Inspect exc.__cause__ for the actual azure.core exception and its status_code to determine the real failure.
For 429/throttling, implement exponential backoff retry (e.g. via tenacity) on VectorSearchExecutionException.
For 404, call ensure_collection_exists() before searching.
For 401/403, refresh/verify credentials (see error 1220).
For 400, validate filter field names and vector dimensions against the index schema.

Example fix

// before
results = await collection.search(values=q)

// after
try:
    results = await collection.search(values=q)
except VectorSearchExecutionException as e:
    cause = e.__cause__          # real azure.core exception
    code = getattr(cause, "status_code", None)
    if code == 429:
        await asyncio.sleep(backoff); ...   # retry
    raise

Defensive patterns

Strategy: retry

Validate before calling

def build_search_kwargs(options, vector=None, values=None) -> dict:
    # validate filter fields & vector dims before calling search
    if options.filter:
        for name in extract_filter_field_names(options.filter):
            assert name in collection.definition.storage_names, f"filter field {name} not in model"
    return {"options": options, "vector": vector, "values": values}

Try / catch

from semantic_kernel.exceptions import VectorSearchExecutionException
import asyncio

async def search_with_retry(collection, **kw, retries=3):
    delay = 0.5
    for attempt in range(retries):
        try:
            return await collection.search(**kw)
        except VectorSearchExecutionException as e:
            code = getattr(e.__cause__, "status_code", None)
            if code == 429 and attempt < retries - 1:
                await asyncio.sleep(delay); delay *= 2
                continue
            raise

Prevention

Always inspect e.__cause__ and its status_code to classify the real failure.
Retry only transient errors (429, 5xx) with exponential backoff; do not retry 400/401/403/404.
Call ensure_collection_exists() before searching to avoid 404.
Validate filter field names and vector dimensions against the index schema before searching.

When it happens

Trigger: Any Azure AI Search service-side or client-side failure during a search call: HTTP 401 (bad/expired credential), 403 (forbidden), 404 (index not found), 429 (throttling), 400 (malformed OData filter / vector dimensions mismatch), or a transient network error. The broad 'except Exception' catches all of them.

Common situations: Expired key or managed identity token; querying an index that was never created (ensure_collection_exists not called); a filter lambda referencing a non-existent field; vector dimension mismatch between query and index; hitting Azure AI Search throughput limits.

Related errors

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