microsoft/semantic-kernel · error · ValueError

Dimensionality of {dimension_num} exceeds the maximum allowe

Error message

Dimensionality of {dimension_num} exceeds the maximum allowed value of {MAX_DIMENSIONALITY}.

What it means

Guard inside `AstraDBMemoryStore.create_collection`: after resolving the effective dimension (`dimension_num or self._embedding_dim`), if it exceeds `MAX_DIMENSIONALITY` (20000) a plain `ValueError` is raised (note: `ValueError`, not `MemoryConnectorInitializationError`). This is the per-collection dimension check, separate from the constructor-level cap.

Source

Thrown at python/semantic_kernel/connectors/memory_stores/astradb/astradb_memory_store.py:127

        dimension_num: int | None = None,
        distance_type: str | None = "cosine_similarity",
    ) -> None:
        """Creates a new collection in Astra if it does not exist.

        Args:
            collection_name (str): The name of the collection to create.
            dimension_num (int): The dimension of the vectors to be stored in this collection.
            distance_type (str): Specifies the similarity metric to be used when querying or comparing vectors within
            this collection. The available options are dot_product, euclidean, and cosine.

        Returns:
            None
        """
        dimension_num = dimension_num if dimension_num is not None else self._embedding_dim
        distance_type = distance_type if distance_type is not None else self._similarity

        if dimension_num > MAX_DIMENSIONALITY:
            raise ValueError(
                f"Dimensionality of {dimension_num} exceeds " + f"the maximum allowed value of {MAX_DIMENSIONALITY}."
            )

        result = await self._client.create_collection(collection_name, dimension_num, distance_type)
        if result is True:
            logger.info(f"Collection {collection_name} created.")

    async def delete_collection(self, collection_name: str) -> None:
        """Deletes a collection.

        Args:
            collection_name (str): The name of the collection to delete.

        Returns:
            None
        """
        result = await self._client.delete_collection(collection_name)
        logger.log(

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass a `dimension_num` <= 20000 that matches your embedding model's output size.
2. If omitting `dimension_num`, ensure the store's `_embedding_dim` is <= 20000.
3. Switch to an embedding model with a supported dimension, or to a different vector store with a higher cap.

Example fix

// before
await store.create_collection("docs", dimension_num=32768)

// after
await store.create_collection("docs", dimension_num=3072)

MAX_DIMENSIONALITY = 20000

def collection_dim_ok(d: int | None, default: int) -> bool:
    eff = d if d is not None else default
    return isinstance(eff, int) and 1 <= eff <= MAX_DIMENSIONALITY

# if collection_dim_ok(dimension_num, store._embedding_dim): await store.create_collection(...)

def is_create_collection_dim_valid(d, default_dim) -> bool:
    eff = d if d is not None else default_dim
    return isinstance(eff, int) and 1 <= eff <= 20000

try:
    await store.create_collection("docs", dimension_num=dim)
except ValueError as e:
    if "exceeds the maximum" in str(e):
        raise ValueError("reduce embedding dimension or pick another store") from e
    raise

When it happens

Trigger: Calling `create_collection(collection_name, dimension_num=D)` with `D > 20000`, or omitting `dimension_num` so it defaults to `self._embedding_dim` which is itself > 20000 (though the constructor usually catches that first).

Common situations: Passing a per-collection dimension override that is too large; the constructor-level guard was bypassed (e.g. store built with a small default dim but create_collection given a huge override); mismatch between configured embedding model and the requested collection dimension.

Related errors

• Dimensionality of {self._embedding_dim} exceeds the maximum
• Failed to create AstraDB settings.
• Vector dimensions must be a positive number.
• Last message in chat history was null or whitespace.
• At least one action must be provided.

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