microsoft/semantic-kernel · error · VectorStoreModelException

Index kind '{field.index_kind}' is not supported by Azure Co

Error message

Index kind '{field.index_kind}' is not supported by Azure Cosmos DB NoSQL container.

What it means

Raised by _create_default_indexing_policy_nosql when a VECTOR field's index_kind is not a key in INDEX_KIND_MAP_NOSQL. Azure Cosmos DB NoSQL supports only FLAT, QUANTIZED_FLAT, DISK_ANN, and DEFAULT. Other IndexKind values (HNSW, IVF_FLAT, DYNAMIC) are valid for other stores but not for Cosmos NoSQL, so building the container indexing policy fails with a VectorStoreModelException during collection creation.

Source

Thrown at python/semantic_kernel/connectors/azure_cosmos_db.py:145

            {
                "path": "/*",
            }
        ],
        "excludedPaths": [
            {
                "path": '/"_etag"/?',
            }
        ],
        "vectorIndexes": [],
    }

    for field in definition.fields:
        if field.field_type == FieldTypes.DATA and (not field.is_full_text_indexed and not field.is_indexed):
            indexing_policy["excludedPaths"].append({"path": f'/"{field.storage_name or field.name}"/*'})

        if field.field_type == FieldTypes.VECTOR:
            if field.index_kind not in INDEX_KIND_MAP_NOSQL:
                raise VectorStoreModelException(
                    f"Index kind '{field.index_kind}' is not supported by Azure Cosmos DB NoSQL container."
                )
            indexing_policy["vectorIndexes"].append({
                "path": f'/"{field.storage_name or field.name}"',
                "type": INDEX_KIND_MAP_NOSQL[field.index_kind],
            })
            # Exclude the vector field from the index for performance optimization.
            indexing_policy["excludedPaths"].append({"path": f'/"{field.storage_name or field.name}"/*'})

    return indexing_policy


def _create_default_vector_embedding_policy(definition: VectorStoreCollectionDefinition) -> dict[str, Any]:
    """Creates a default vector embedding policy for the Azure Cosmos DB NoSQL container.

    A default vector embedding policy is created based on the data model definition.

    Args:

View on GitHub (pinned to c028a0c7dc)

Solutions

Set the vector field's index_kind to IndexKind.FLAT, IndexKind.QUANTIZED_FLAT, IndexKind.DISK_ANN, or IndexKind.DEFAULT for Cosmos DB NoSQL.
Use DISK_ANN for large-scale vector datasets (the Cosmos-recommended ANN option) or QUANTIZED_FLAT for smaller datasets needing compression.
Validate all vector field index_kinds against INDEX_KIND_MAP_NOSQL before creating the container.

Example fix

// before
field(type_='float', name='embedding', index_kind=IndexKind.HNSW)

// after
field(type_='float', name='embedding', index_kind=IndexKind.DISK_ANN)

Defensive patterns

Strategy: validation

Validate before calling

from semantic_kernel.connectors.azure_cosmos_db import INDEX_KIND_MAP_NOSQL

def validate_cosmos_vector_kinds(definition) -> list[str]:
    bad = []
    for f in definition.fields:
        if f.field_type.value == "vector" and f.index_kind not in INDEX_KIND_MAP_NOSQL:
            bad.append(f"{f.name}: {f.index_kind}")
    return bad

assert not validate_cosmos_vector_kinds(definition)

Try / catch

from semantic_kernel.exceptions import VectorStoreModelException
try:
    await collection.ensure_collection_exists()
except VectorStoreModelException as e:
    if "not supported by Azure Cosmos DB NoSQL" in str(e):
        # change index_kind to DISK_ANN / QUANTIZED_FLAT / FLAT / DEFAULT
        ...
    raise

Prevention

For Cosmos DB NoSQL, use FLAT, QUANTIZED_FLAT, DISK_ANN, or DEFAULT only.
Re-map index_kind when porting a definition from Azure AI Search (HNSW) or MongoDB (IVF_FLAT/HNSW).
Validate vector index_kinds against INDEX_KIND_MAP_NOSQL in a test before container creation.

When it happens

Trigger: Creating a Cosmos DB NoSQL collection (ensure_collection_exists) whose definition sets a vector field's index_kind to IndexKind.HNSW, IndexKind.IVF_FLAT, or IndexKind.DYNAMIC. Fires while constructing the default indexing policy from the definition, before any Azure call.

Common situations: Porting a model from Azure AI Search (which uses HNSW) or MongoDB Atlas (IVF_FLAT/HNSW) to Cosmos DB NoSQL without changing index_kind; using DEFAULT and assuming it maps to HNSW (it maps to FLAT in Cosmos NoSQL, which is valid, so DEFAULT itself won't trigger this).

Related errors

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