{"record":{"id":"3afa6fe4d98f90a9","repo":"microsoft/semantic-kernel","slug":"dimensionality-of-dimension-num-exceeds-the-maxi","errorCode":null,"errorMessage":"Dimensionality of {dimension_num} exceeds the maximum allowed value of {MAX_DIMENSIONALITY}.","messagePattern":"Dimensionality of (.+?) exceeds the maximum allowed value of (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/memory_stores/astradb/astradb_memory_store.py","lineNumber":127,"sourceCode":"        dimension_num: int | None = None,\n        distance_type: str | None = \"cosine_similarity\",\n    ) -> None:\n        \"\"\"Creates a new collection in Astra if it does not exist.\n\n        Args:\n            collection_name (str): The name of the collection to create.\n            dimension_num (int): The dimension of the vectors to be stored in this collection.\n            distance_type (str): Specifies the similarity metric to be used when querying or comparing vectors within\n            this collection. The available options are dot_product, euclidean, and cosine.\n\n        Returns:\n            None\n        \"\"\"\n        dimension_num = dimension_num if dimension_num is not None else self._embedding_dim\n        distance_type = distance_type if distance_type is not None else self._similarity\n\n        if dimension_num > MAX_DIMENSIONALITY:\n            raise ValueError(\n                f\"Dimensionality of {dimension_num} exceeds \" + f\"the maximum allowed value of {MAX_DIMENSIONALITY}.\"\n            )\n\n        result = await self._client.create_collection(collection_name, dimension_num, distance_type)\n        if result is True:\n            logger.info(f\"Collection {collection_name} created.\")\n\n    async def delete_collection(self, collection_name: str) -> None:\n        \"\"\"Deletes a collection.\n\n        Args:\n            collection_name (str): The name of the collection to delete.\n\n        Returns:\n            None\n        \"\"\"\n        result = await self._client.delete_collection(collection_name)\n        logger.log(","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/memory_stores/astradb/astradb_memory_store.py#L109-L145","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass a `dimension_num` <= 20000 that matches your embedding model's output size.","If omitting `dimension_num`, ensure the store's `_embedding_dim` is <= 20000.","Switch to an embedding model with a supported dimension, or to a different vector store with a higher cap."],"exampleFix":"// before\nawait store.create_collection(\"docs\", dimension_num=32768)\n\n// after\nawait store.create_collection(\"docs\", dimension_num=3072)","handlingStrategy":"validation","validationCode":"MAX_DIMENSIONALITY = 20000\n\ndef collection_dim_ok(d: int | None, default: int) -> bool:\n    eff = d if d is not None else default\n    return isinstance(eff, int) and 1 <= eff <= MAX_DIMENSIONALITY\n\n# if collection_dim_ok(dimension_num, store._embedding_dim): await store.create_collection(...)","typeGuard":"def is_create_collection_dim_valid(d, default_dim) -> bool:\n    eff = d if d is not None else default_dim\n    return isinstance(eff, int) and 1 <= eff <= 20000","tryCatchPattern":"try:\n    await store.create_collection(\"docs\", dimension_num=dim)\nexcept ValueError as e:\n    if \"exceeds the maximum\" in str(e):\n        raise ValueError(\"reduce embedding dimension or pick another store\") from e\n    raise","preventionTips":["Validate per-collection dimension overrides against the 20000 cap before calling create_collection.","Keep collection dimension consistent with the embedding model and the store default.","Document the cap next to your embedding model selection."],"tags":["astra-db","vector-dimension","validation","create-collection","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}