microsoft/graphrag · error · ValueError

CosmosDB Storage requires 'connection_string' or 'account_ur

Error message

CosmosDB Storage requires 'connection_string' or 'account_url'.

What it means

After ruling out a missing database and conflicting credentials, the constructor requires at least one endpoint: either connection_string or account_url. With neither, there is no way to reach the Cosmos account, so construction fails fast instead of failing later during I/O.

Source

Thrown at packages/graphrag-storage/graphrag_storage/azure_cosmos_storage.py:82

        logger.info("Creating CosmosDB key-value storage")
        if not database_name:
            msg = "CosmosDB Storage requires 'database_name'."
            raise ValueError(msg)

        if connection_string is not None and account_url is not None:
            msg = "Specify either 'connection_string' or 'account_url', not both."
            raise ValueError(msg)

        if connection_string:
            self._cosmos_client = CosmosClient.from_connection_string(connection_string)
        elif account_url:
            self._cosmos_client = CosmosClient(
                url=account_url,
                credential=DefaultAzureCredential(),
            )
        else:
            msg = "CosmosDB Storage requires 'connection_string' or 'account_url'."
            raise ValueError(msg)

        self._encoding = encoding
        self._database_name = database_name
        self._connection_string = connection_string
        self._cosmosdb_account_url = account_url
        self._container_name = container_name
        self._namespace = namespace
        self._database_client = None
        self._container_client = None

        self._create_database()
        self._create_container()

    # ------------------------------------------------------------------
    # Internal DB / container management
    # ------------------------------------------------------------------

    def _create_database(self) -> None:

View on GitHub (pinned to f40e9a26ce)

Solutions

1. Set the connection string env var (or pass connection_string=...)
2. Or pass account_url and ensure DefaultAzureCredential can authenticate (az login, managed identity, etc.)
3. Print/verify effective config before pipeline start to catch empty values

Example fix

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

import os
conn = os.environ.get("GRAPHRAG_COSMOSDB_CONNECTION_STRING")
url = os.environ.get("GRAPHRAG_COSMOSDB_ACCOUNT_URL")
assert conn or url, "COSMOS credentials missing"

When it happens

Trigger: Calling AzureCosmosStorage with both connection_string=None and account_url=None — typically because the env vars holding them were never set in the runtime environment.

Common situations: Deploying to a container/CI where GRAPHRAG_COSMOSDB_CONNECTION_STRING was not injected; typo'd env var name; local .env not loaded.

Related errors

• CosmosTableProvider requires 'connection_string' or 'account
• Either connection_string or url must be provided for CosmosD
• api_key must be set when auth_method=api_key.
• CosmosDB Storage requires 'database_name'.
• Specify either 'connection_string' or 'account_url', not bot

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