{"record":{"id":"3957832c8c9341b0","repo":"microsoft/semantic-kernel","slug":"failed-to-search-items","errorCode":null,"errorMessage":"Failed to search items.","messagePattern":"Failed to search items\\.","errorType":"exception","errorClass":"VectorSearchExecutionException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/azure_cosmos_db.py","lineNumber":856,"sourceCode":"                raise VectorStoreModelException(\"Hybrid search requires 'keyword_field_name' in options.\")\n            distance_clause = (\n                f\"RRF(VectorDistance(c.{vector_field_name}, @vector), FullTextScore(c.{text_field}, @keywords))\"\n            )\n        else:\n            raise VectorStoreModelException(f\"Search type '{search_type}' is not supported.\")\n        query = (\n            f\"SELECT TOP @top {select_clause}, \"  # nosec: B608\n            f\"{distance_clause} as {NOSQL_SCORE_PROPERTY_NAME} \"  # nosec: B608\n            \"FROM c \"\n            f\"{where_clauses}\"  # nosec: B608\n            f\"ORDER BY {distance_clause}\"  # nosec: B608\n        )\n\n        container_proxy = await self._get_container_proxy(self.collection_name, **kwargs)\n        try:\n            results = container_proxy.query_items(query, parameters=params)\n        except Exception as exc:\n            raise VectorSearchExecutionException(\"Failed to search items.\") from exc\n        return KernelSearchResults(\n            results=self._get_vector_search_results_from_results(results, options),\n            total_count=None,\n        )\n\n    def _build_select_clause(self, include_vectors: bool) -> str:\n        \"\"\"Create the select clause for a CosmosDB query.\"\"\"\n        included_fields = [field for field in self.definition.get_storage_names(include_vector_fields=include_vectors)]\n        if self.definition.key_name != COSMOS_ITEM_ID_PROPERTY_NAME:\n            # Replace the key field name with the Cosmos item id property name\n            included_fields = [\n                field if field != self.definition.key_name else COSMOS_ITEM_ID_PROPERTY_NAME\n                for field in included_fields\n            ]\n\n        return \", \".join(f\"c.{field}\" for field in included_fields)\n\n    @override","sourceCodeStart":838,"sourceCodeEnd":874,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/azure_cosmos_db.py#L838-L874","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nresults = await store.search(vector, options)  # opaque 'Failed to search items.'\n// after\ntry:\n    results = await store.search(vector, options)\nexcept VectorSearchExecutionException as e:\n    raise RuntimeError(f\"Cosmos query failed: {e.__cause__}\") from e\n","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"from semantic_kernel.exceptions import VectorSearchExecutionException\n\ntry:\n    results = await store.search(vector, options)\nexcept VectorSearchExecutionException as e:\n    cause = e.__cause__\n    status = getattr(getattr(cause, \"response\", None), \"status_code\", None)\n    if status == 429:\n        # throttled: backoff and retry\n        ...\n    raise RuntimeError(f\"Cosmos search failed: {cause}\") from e","preventionTips":["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."],"tags":["azure-cosmos-db","vector-search","runtime","network"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}