microsoft/graphrag · error · ValueError

CosmosTableProvider requires 'connection_string' or 'account

Error message

CosmosTableProvider requires 'connection_string' or 'account_url'.

What it means

CosmosTableProvider's constructor verifies that at least one endpoint credential (connection_string or account_url) is present after the mutual-exclusion check. With neither, no Cosmos client can be built, so it fails fast with a clear config error.

Source

Thrown at packages/graphrag-storage/graphrag_storage/tables/cosmos_table_provider.py:100

            self._container = _container
            self._legacy_container = _legacy_container
            self._namespace = namespace
            self._owns_client = False
            return

        # Normal construction from config values.
        if not database_name:
            msg = "CosmosTableProvider requires 'database_name'."
            raise ValueError(msg)
        if not container_name:
            msg = "CosmosTableProvider requires 'container_name'."
            raise ValueError(msg)
        if connection_string and account_url:
            msg = "Specify either 'connection_string' or 'account_url', not both."
            raise ValueError(msg)
        if not connection_string and not account_url:
            msg = "CosmosTableProvider requires 'connection_string' or 'account_url'."
            raise ValueError(msg)

        if connection_string:
            self._cosmos_client = CosmosClient.from_connection_string(connection_string)
        else:
            self._cosmos_client = CosmosClient(
                url=account_url,  # type: ignore[arg-type]
                credential=DefaultAzureCredential(),
            )

        self._namespace = namespace
        self._owns_client = True

        # Containers are created lazily on first use via _ensure_container().
        self._database_name = database_name
        self._container_name = container_name
        self._legacy_container_name = legacy_container
        self._container: ContainerProxy | None = None  # type: ignore[assignment]
        self._legacy_container: ContainerProxy | None = None

View on GitHub (pinned to f40e9a26ce)

Solutions

Provide connection_string or url in the table provider config
Verify the corresponding env var is exported in the runtime (echo $VAR)
For url auth, ensure DefaultAzureCredential works (az login locally, managed identity in Azure)

Example fix

# before
type: cosmosdb
database_name: graphrag
container_name: tables
# after
type: cosmosdb
database_name: graphrag
container_name: tables
connection_string: ${GRAPHRAG_COSMOS_CONN}

Defensive patterns

Strategy: validation

Validate before calling

assert cfg.get("connection_string") or cfg.get("url"), "cosmos table provider needs a credential"

Prevention

Startup config check that fails before any pipeline work
Document required env vars per environment

When it happens

Trigger: Creating CosmosTableProvider from config where both credential fields are absent — unset env vars, empty YAML placeholders, or a secrets file not loaded.

Common situations: CI/CD job missing the cosmos secret; local run without .env loaded; placeholder values like ${VAR} left unresolved because the var is undefined.

Related errors

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