microsoft/semantic-kernel · error · VectorStoreModelDeserializationException

The record does not have the {COSMOS_ITEM_ID_PROPERTY_NAME}

Error message

The record does not have the {COSMOS_ITEM_ID_PROPERTY_NAME} property.

What it means

During deserialization the store expects every returned Cosmos document to contain the canonical 'id' property (COSMOS_ITEM_ID_PROPERTY_NAME). If a record lacks it, VectorStoreModelDeserializationException is raised before mapping id back to the data model's key field. This guards the key-rename logic (which copies record[id] into the model key field) from a KeyError.

Source

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

        key_field_name = self.definition.key_name
        for record in records:
            serialized_record = {**record, COSMOS_ITEM_ID_PROPERTY_NAME: record[key_field_name]}
            if key_field_name != COSMOS_ITEM_ID_PROPERTY_NAME:
                # Remove the key field from the serialized record
                serialized_record.pop(key_field_name, None)

            serialized_records.append(serialized_record)

        return serialized_records

    @override
    def _deserialize_store_models_to_dicts(self, records: Sequence[Any], **kwargs: Any) -> Sequence[dict[str, Any]]:
        deserialized_records = []

        key_field_name = self.definition.key_name
        for record in records:
            if COSMOS_ITEM_ID_PROPERTY_NAME not in record:
                raise VectorStoreModelDeserializationException(
                    f"The record does not have the {COSMOS_ITEM_ID_PROPERTY_NAME} property."
                )

            deserialized_record = {**record, key_field_name: record[COSMOS_ITEM_ID_PROPERTY_NAME]}
            if key_field_name != COSMOS_ITEM_ID_PROPERTY_NAME:
                # Remove the id property from the deserialized record
                deserialized_record.pop(COSMOS_ITEM_ID_PROPERTY_NAME, None)

            deserialized_records.append(deserialized_record)

        return deserialized_records

    @override
    async def ensure_collection_exists(self, **kwargs) -> None:
        indexing_policy = kwargs.pop("indexing_policy", _create_default_indexing_policy_nosql(self.definition))
        vector_embedding_policy = kwargs.pop(
            "vector_embedding_policy", _create_default_vector_embedding_policy(self.definition)
        )

View on GitHub (pinned to c028a0c7dc)

Solutions

Ensure all stored documents include the 'id' property; write records through the store's upsert/create so the serializer always sets COSMOS_ITEM_ID_PROPERTY_NAME.
If selecting a subset of fields, always include id in the projection so deserialization succeeds.
When ingesting external documents, map their identifier into the 'id' field before storing/deserializing.

Example fix

// before
await store.get([record_id])  # document in Cosmos is missing the 'id' field
// after
# ensure documents are written with 'id' present:
await store.upsert({"id": record_id, **other_fields})

Defensive patterns

Strategy: validation

Validate before calling

from semantic_kernel.connectors.azure_cosmos_db import COSMOS_ITEM_ID_PROPERTY_NAME
for rec in records:
    if COSMOS_ITEM_ID_PROPERTY_NAME not in rec:
        raise ValueError(f"Record missing required '{COSMOS_ITEM_ID_PROPERTY_NAME}'")

Type guard

def has_id(rec: dict) -> bool:
    return COSMOS_ITEM_ID_PROPERTY_NAME in rec

Prevention

Always write records through the store's upsert/create so 'id' is set automatically.
Include 'id' in any SELECT projection used for deserialization.
Map external identifiers into the 'id' field before storing.

When it happens

Trigger: A document retrieved from Cosmos (via get/upsert return or a manual dict passed through deserialization) has no 'id' field. Typically this happens when raw records not created through the store are deserialized, or a projection/query selected only some fields and omitted id.

Common situations: Using a SELECT projection that excludes id and feeding the result into deserialization; documents written by another system that uses a different id convention; or partially-constructed dicts passed to internal deserialize paths.

Related errors

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