microsoft/semantic-kernel · error · ServiceResponseException

Astra DB request error - {response_dict['errors']}

Error message

Astra DB request error - {response_dict['errors']}

What it means

Raised by `AstraClient._run_query` when the HTTP response from Astra DB returns status 200 but the JSON body contains an `errors` key. Astra DB conveys application-level/data-plane errors (e.g. invalid query, missing collection, key issues) inside a 200 response body, so the client inspects the payload and throws a `ServiceResponseException` embedding the raw error list.

Source

Thrown at python/semantic_kernel/connectors/memory_stores/astradb/astra_client.py:57

        self.request_base_url = (
            f"https://{self.astra_id}-{self.astra_region}.apps.astra.datastax.com/api/json/v1/{self.keyspace_name}"
        )
        self.request_header = {
            "x-cassandra-token": self.astra_application_token,
            "Content-Type": "application/json",
            "User-Agent": ASTRA_CALLER_IDENTITY,
        }
        self._session = session

    async def _run_query(self, request_url: str, query: dict):
        async with (
            AsyncSession(self._session) as session,
            session.post(request_url, data=json.dumps(query), headers=self.request_header) as response,
        ):
            if response.status == 200:
                response_dict = await response.json()
                if "errors" in response_dict:
                    raise ServiceResponseException(f"Astra DB request error - {response_dict['errors']}")
                return response_dict
            raise ServiceResponseException(f"Astra DB not available. Status : {response}")

    async def find_collections(self, include_detail: bool = True):
        """Finds all collections in the keyspace."""
        query = {"findCollections": {"options": {"explain": include_detail}}}
        result = await self._run_query(self.request_base_url, query)
        return result["status"]["collections"]

    async def find_collection(self, collection_name: str):
        """Finds a collection in the keyspace."""
        collections = await self.find_collections(False)
        found = False
        for collection in collections:
            if collection == collection_name:
                found = True
                break
        return found

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Read the `errors` array in the message to identify the precise Astra-side reason and address it (e.g. create the missing collection, fix the dimension).
2. Verify the collection/keyspace names and that they exist via `find_collections`.
3. Confirm the embedding dimension used in queries matches the collection's configured dimension.
4. Ensure the Astra application token has the correct scope and belongs to the right database/region.
5. Retry on transient Astra-side errors with exponential backoff.

Example fix

// before
await store.get("my_collection", "missing-key")  # 200 with errors payload

// after
cols = await store.get_collections()
assert "my_collection" in cols, f"collection missing; available: {cols}"
rec = await store.get("my_collection", "valid-key")

# pre-flight: confirm the collection exists and dims match
async def ensure_astra_ready(store, collection, dim):
    cols = await store.get_collections()
    if collection not in cols:
        await store.create_collection(collection, dimension_num=dim)
    return True

from semantic_kernel.exceptions import ServiceResponseException
try:
    rec = await store.get("coll", "k")
except ServiceResponseException as e:
    msg = str(e)
    if "request error" in msg:
        errors = msg.split("-", 1)[1]
        # parse the Astra errors list and decide: create collection, fix dims, etc.
        raise
    raise

When it happens

Trigger: Any async Astra operation (`find_collections`, `find_collection`, `create_collection`, `find_documents`, etc.) whose POST to the Astra REST API returns `{..., "errors": [...]}`. Common triggers: referencing a non-existent collection/keyspace, malformed vector dimensions in the query, an incompatible API payload, or a token that authenticates but lacks data-plane permission on the resource.

Common situations: Misconfigured collection name or keyspace; embedding dimension mismatch between stored collection and query; stale app token scoped to the wrong database; Astra rolling out a backend change that alters the response shape; passing a filter or option field Astra rejects.

Related errors

• Astra DB not available. Status : {response}
• No token received from token generation.
• Failed to generate token using bot_secret.
• No token received.
• Failed to fetch token from token endpoint.

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