microsoft/graphrag · error · ValueError

CosmosDB requires the id_field to be 'id'.

Error message

CosmosDB requires the id_field to be 'id'.

What it means

The CosmosDB vector store hard-requires id_field == "id" because Cosmos documents' partition/identity key is the immutable 'id' property; the store maps vector record IDs onto it and cannot honor a custom id_field like other backends. The check runs first in __init__ before credential validation.

Source

Thrown at packages/graphrag-vectors/graphrag_vectors/cosmosdb.py:45

class CosmosDBVectorStore(VectorStore):
    """Azure CosmosDB vector storage implementation."""

    _cosmos_client: CosmosClient
    _database_client: DatabaseProxy
    _container_client: ContainerProxy

    def __init__(
        self,
        database_name: str,
        connection_string: str | None = None,
        url: str | None = None,
        **kwargs,
    ):
        super().__init__(**kwargs)
        if self.id_field != "id":
            msg = "CosmosDB requires the id_field to be 'id'."
            raise ValueError(msg)
        if not connection_string and not url:
            msg = "Either connection_string or url must be provided for CosmosDB."
            raise ValueError(msg)

        self.database_name = database_name
        self.connection_string = connection_string
        self.url = url

    def connect(self) -> Any:
        """Connect to CosmosDB vector storage."""
        if self.connection_string:
            self._cosmos_client = CosmosClient.from_connection_string(
                self.connection_string
            )
        else:
            self._cosmos_client = CosmosClient(
                url=self.url, credential=DefaultAzureCredential()
            )

View on GitHub (pinned to f40e9a26ce)

Solutions

1. Remove id_field from the cosmosdb vector store config or set it to "id"
2. If a custom id_field is a hard requirement, choose a different vector backend

Example fix

# before
CosmosDBVectorStore(id_field="text_id", ...)
# after
CosmosDBVectorStore(id_field="id", ...)  # or omit id_field

cfg.pop("id_field", None)
cfg["id_field"] = "id"

When it happens

Trigger: Instantiating the CosmosDB vector store with id_field="text_id" (or a config/base class default other than "id").

Common situations: Copying vector store config from a LanceDB/Postgres setup that sets a custom id_field; a base class defaulting id_field to something else that the caller didn't override.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• CosmosDB Storage requires 'database_name'.
• CosmosTableProvider requires 'database_name'.
• CosmosTableProvider requires 'container_name'.
• url must be provided for Azure AI Search.
• Either connection_string or url must be provided for CosmosD

AI-assisted analysis of microsoft/graphrag@f40e9a26ce (2026-08-27). Data as JSON: /api/errors/321f7b2eea9308b7. Report an issue: GitHub.