microsoft/graphrag · error · ValueError

CosmosDB Storage requires 'database_name'.

Error message

CosmosDB Storage requires 'database_name'.

What it means

AzureCosmosStorage's constructor requires a database_name because CosmosDB organizes all containers inside a named database; without it the SDK has no target to create or fetch. The check runs before any client is constructed, so nothing is connected yet when it fires. It is a configuration-validation error from graphrag-storage's CosmosDB key-value store.

Source

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

    _container_name: str
    _encoding: str
    _namespace: str

    def __init__(
        self,
        database_name: str,
        container_name: str,
        connection_string: str | None = None,
        account_url: str | None = None,
        encoding: str = "utf-8",
        namespace: str = "",
        **kwargs: Any,
    ) -> None:
        """Create a CosmosDB key-value storage instance."""
        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

View on GitHub (pinned to f40e9a26ce)

Solutions

1. Set database_name in the storage config (e.g. type: azure_cosmos, database_name: mygraphrag) or pass database_name="mydb" to the constructor
2. If using settings.yaml, verify the key sits under the correct storage section and is not shadowed by an env-var prefix mistake
3. Confirm the database exists in your Cosmos account or that the account has permission to create it

Example fix

# before
storage = AzureCosmosStorage(connection_string=conn_str)
# after
storage = AzureCosmosStorage(connection_string=conn_str, database_name="graphrag")

if not cfg.get("database_name"):
    raise SystemExit("Set storage.database_name before creating Cosmos storage")

When it happens

Trigger: Instantiating AzureCosmosStorage (directly or via StorageFactory with type azure_cosmos) with database_name=None, an empty string, or omitting it from the storage config kwargs.

Common situations: Copied a blob/file-storage config where database_name is not a field; YAML/env override left the value blank; relied on a connection string assuming the database is implied (it is not in CosmosDB).

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• CosmosTableProvider requires 'database_name'.
• CosmosTableProvider requires 'container_name'.
• CosmosDB requires the id_field to be 'id'.
• TemplateEngineConfig.template_manager '{strategy}' is not re
• request_id needs to be passed as a keyword argument

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