microsoft/graphrag · error · ValueError

CosmosTableProvider requires 'container_name'.

Error message

CosmosTableProvider requires 'container_name'.

What it means

CosmosTableProvider stores each table as documents inside a Cosmos container, so container_name is mandatory in the config-based constructor path. Without it there is no target container and the provider refuses to construct.

Source

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

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

        self._namespace = namespace
        self._owns_client = True

View on GitHub (pinned to f40e9a26ce)

Solutions

1. Set container_name (e.g. container_name: graphrag_tables) in the cosmos table provider config
2. Use a stable name — the provider namespaces tables inside this single container
3. Confirm the container exists or the account allows auto-creation

Example fix

# before
type: cosmosdb
database_name: graphrag
# after
type: cosmosdb
database_name: graphrag
container_name: graphrag_tables

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

When it happens

Trigger: Creating CosmosTableProvider from config with database_name set but container_name missing/empty.

Common situations: Config template copied only the database/credential keys; container name expected to default to the table name (it does not — one container holds all tables namespaced).

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'.
• 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/38fbf2d5b59b8f9e. Report an issue: GitHub.