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

Inspect the chained exception: str(exc.__cause__) reveals the real CosmosHttpResponseError status code and message.

microsoft/semantic-kernel · error · VectorSearchExecutionException

Failed to search items.

Error message

Failed to search items.

What it means

A generic VectorSearchExecutionException wrapping any exception thrown by the Cosmos SDK's query_items call while executing the assembled vector search SQL. The original SDK error is chained (from exc), so the true cause (auth, throttling/429, malformed query, network, indexing policy mismatch) is in __cause__. The connector does not classify the underlying failure, so every problem during query execution surfaces as this single message.

Source

Thrown at python/semantic_kernel/connectors/azure_cosmos_db.py:856

                raise VectorStoreModelException("Hybrid search requires 'keyword_field_name' in options.")
            distance_clause = (
                f"RRF(VectorDistance(c.{vector_field_name}, @vector), FullTextScore(c.{text_field}, @keywords))"
            )
        else:
            raise VectorStoreModelException(f"Search type '{search_type}' is not supported.")
        query = (
            f"SELECT TOP @top {select_clause}, "  # nosec: B608
            f"{distance_clause} as {NOSQL_SCORE_PROPERTY_NAME} "  # nosec: B608
            "FROM c "
            f"{where_clauses}"  # nosec: B608
            f"ORDER BY {distance_clause}"  # nosec: B608
        )

        container_proxy = await self._get_container_proxy(self.collection_name, **kwargs)
        try:
            results = container_proxy.query_items(query, parameters=params)
        except Exception as exc:
            raise VectorSearchExecutionException("Failed to search items.") from exc
        return KernelSearchResults(
            results=self._get_vector_search_results_from_results(results, options),
            total_count=None,
        )

    def _build_select_clause(self, include_vectors: bool) -> str:
        """Create the select clause for a CosmosDB query."""
        included_fields = [field for field in self.definition.get_storage_names(include_vector_fields=include_vectors)]
        if self.definition.key_name != COSMOS_ITEM_ID_PROPERTY_NAME:
            # Replace the key field name with the Cosmos item id property name
            included_fields = [
                field if field != self.definition.key_name else COSMOS_ITEM_ID_PROPERTY_NAME
                for field in included_fields
            ]

        return ", ".join(f"c.{field}" for field in included_fields)

    @override

View on GitHub (pinned to c028a0c7dc)

Solutions

Inspect the chained exception: str(exc.__cause__) reveals the real CosmosHttpResponseError status code and message.
For 429/4xx throttle errors, raise provisioned RU/s or implement backoff retry at the caller level; verify the partition key matches the collection design.
Confirm the vector index policy's distance function and dimensions match the field metadata and the query vector.
Check credentials and endpoint configuration in the store settings and that the key/Entra identity has read/query permission on the container.

Example fix

// before
results = await store.search(vector, options)  # opaque 'Failed to search items.'
// after
try:
    results = await store.search(vector, options)
except VectorSearchExecutionException as e:
    raise RuntimeError(f"Cosmos query failed: {e.__cause__}") from e

Defensive patterns

Strategy: retry

Try / catch

from semantic_kernel.exceptions import VectorSearchExecutionException

try:
    results = await store.search(vector, options)
except VectorSearchExecutionException as e:
    cause = e.__cause__
    status = getattr(getattr(cause, "response", None), "status_code", None)
    if status == 429:
        # throttled: backoff and retry
        ...
    raise RuntimeError(f"Cosmos search failed: {cause}") from e

Prevention

Provision enough RU/s for query load to avoid 429 throttling.
Verify vector index policy (distance function, dimensions) matches the field and query.
Check credentials/permissions on the container before querying.
Always inspect __cause__ to classify the real failure.

When it happens

Trigger: container_proxy.query_items(query, parameters=params) raises. Common underlying causes: insufficient RBAC/key permissions on the container, HTTP 429 throttling when RU/s are exceeded, a vector index that does not match the distance function, missing/incorrect indexing policy, network/connectivity failures, or a query referencing fields that do not exist on the server.

Common situations: Provisioned throughput too low (429), wrong partition key routing, mismatched vector dimensionality between the stored vectors and the query vector, using a distance function in the query that the vector embedding policy/index does not declare, or expired/invalid Cosmos credentials.

Related errors

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