microsoft/semantic-kernel · error · MemoryConnectorInitializationError

Dimensionality of {self._embedding_dim} exceeds the maximum

Error message

Dimensionality of {self._embedding_dim} exceeds the maximum allowed value of {MAX_DIMENSIONALITY}.

What it means

Constructor guard in `AstraDBMemoryStore.__init__`: after settings are built, if the configured `embedding_dim` exceeds `MAX_DIMENSIONALITY` (20000, defined in the same module) a `MemoryConnectorInitializationError` is raised. Astra DB cannot store vectors above this dimensionality, so the store refuses to initialize.

Source

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

        """
        try:
            astradb_settings = AstraDBSettings(
                app_token=astra_application_token,
                db_id=astra_id,
                region=astra_region,
                keyspace=keyspace_name,
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
            )
        except ValidationError as ex:
            raise MemoryConnectorInitializationError("Failed to create AstraDB settings.", ex) from ex

        self._embedding_dim = embedding_dim
        self._similarity = similarity
        self._session = session

        if self._embedding_dim > MAX_DIMENSIONALITY:
            raise MemoryConnectorInitializationError(
                f"Dimensionality of {self._embedding_dim} exceeds the maximum allowed value of {MAX_DIMENSIONALITY}."
            )

        self._client = AstraClient(
            astra_id=astradb_settings.db_id,
            astra_region=astradb_settings.region,
            astra_application_token=(
                astradb_settings.app_token.get_secret_value() if astradb_settings.app_token else None
            ),
            keyspace_name=astradb_settings.keyspace,
            embedding_dim=embedding_dim,
            similarity_function=similarity,
            session=self._session,
        )

    async def get_collections(self) -> list[str]:
        """Gets the list of collections.

View on GitHub (pinned to c028a0c7dc)

Solutions

Use an embedding model whose output dimension is <= 20000 (e.g. switch to a model that supports Matryoshka/shorter dims).
Correct the `embedding_dim` value to the model's actual vector size.
If you genuinely need higher dims, choose a different vector store backend without this cap.

Example fix

// before
store = AstraDBMemoryStore(..., embedding_dim=32768)  # > MAX_DIMENSIONALITY(20000)

// after
store = AstraDBMemoryStore(..., embedding_dim=3072)  # within Astra limit

Defensive patterns

Strategy: validation

Validate before calling

MAX_DIMENSIONALITY = 20000  # AstraDB cap in SK

def valid_astra_dim(d: int) -> bool:
    return isinstance(d, int) and 0 < d <= MAX_DIMENSIONALITY

# assert valid_astra_dim(embedding_dim) before constructing the store

Type guard

def is_valid_embedding_dim(d) -> bool:
    return isinstance(d, int) and 1 <= d <= 20000

Try / catch

from semantic_kernel.exceptions import MemoryConnectorInitializationError
try:
    store = AstraDBMemoryStore(..., embedding_dim=dim)
except MemoryConnectorInitializationError as e:
    if "exceeds the maximum" in str(e):
        dim = choose_smaller_dim_model()
    raise

Prevention

Read the embedding model's documented output dimension and assert it is <= 20000 before use with Astra.
Keep the dimension value in a single config source to avoid divergence.
Consider Matryoshka-capable models to reduce dimensionality when needed.

When it happens

Trigger: Passing an `embedding_dim` > 20000 to the `AstraDBMemoryStore` constructor, typically driven by the embedding model's output size. This is a hard cap enforced before any client/network interaction.

Common situations: Using a very-high-dimensional embedding model; accidentally passing the model parameter count or token count instead of the embedding dimension; misconfigured dimension sourced from config; a future model whose native dim exceeds 20000.

Related errors

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