microsoft/graphrag · error · ValueError

CosmosTableProvider requires 'database_name'.

Error message

CosmosTableProvider requires 'database_name'.

What it means

CosmosTableProvider (the dataframe table backend for CosmosDB) requires a database_name because every container lives inside a database. The check runs in the config-based constructor path (it returns early when constructed from an existing client). It fires before any network call.

Source

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

        _container: ContainerProxy | None = None,
        _legacy_container: ContainerProxy | None = None,
        **kwargs: Any,
    ) -> None:
        self._batch_size = min(max(batch_size, 1), _MAX_BATCH_SIZE)

        if _container is not None:
            # Fast path: child() or test injection.
            self._cosmos_client = _cosmos_client
            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(),
            )

View on GitHub (pinned to f40e9a26ce)

Solutions

1. Add database_name to the table provider (table_storage) config section
2. Verify credentials were not the only keys copied from another cosmos config block
3. Ensure the database exists or the identity can create it

Example fix

# before
type: cosmosdb
connection_string: ${GRAPHRAG_COSMOS_CONN}
# after
type: cosmosdb
connection_string: ${GRAPHRAG_COSMOS_CONN}
database_name: graphrag_tables

assert cfg.get("database_name"), "table_storage needs database_name for cosmosdb"

When it happens

Trigger: Creating CosmosTableProvider via TableProviderFactory with type cosmosdb but no database_name in the table storage config, or instantiating it directly without database_name.

Common situations: settings.yaml defines cosmosdb credentials but omits the database_name key under table_storage; assuming the provider reads the database from the vector/storage config section instead.

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 'container_name'.
• CosmosDB Storage requires 'database_name'.
• CosmosDB requires the id_field to be 'id'.
• Specify either 'connection_string' or 'account_url', not bot
• CosmosTableProvider requires 'connection_string' or 'account

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