microsoft/graphrag · error · ValueError

Either connection_string or url must be provided for CosmosD

Error message

Either connection_string or url must be provided for CosmosDB.

What it means

The CosmosDB vector store requires exactly one of connection_string or url to build its client; with both absent it cannot reach any account and __init__ raises immediately. url-mode relies on DefaultAzureCredential underneath.

Source

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

    _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()
            )

        self._create_database()
        self._create_container()

View on GitHub (pinned to f40e9a26ce)

Solutions

1. Set connection_string (env var or YAML) for key-based auth
2. Or set url to the account endpoint and ensure DefaultAzureCredential resolves (az login / managed identity)
3. Validate effective config at startup before the pipeline runs

Example fix

# before
CosmosDBVectorStore(database_name="graphrag")
# after
CosmosDBVectorStore(database_name="graphrag", connection_string=os.environ["COSMOS_CONN_STR"])

assert cfg.get("connection_string") or cfg.get("url"), "cosmos vector store needs a credential"

When it happens

Trigger: Creating the CosmosDB vector store with neither connection_string nor url — unset env vars, empty YAML values, or unresolved ${placeholders}.

Common situations: Deployment missing the cosmos secret; .env not loaded locally; placeholder left because the env var name doesn't match what the config expects.

Related errors

• CosmosDB Storage requires 'connection_string' or 'account_ur
• CosmosTableProvider requires 'connection_string' or 'account
• url must be provided for Azure AI Search.
• CosmosDB requires the id_field to be 'id'.
• api_key must be set when auth_method=api_key.

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