microsoft/graphrag · error · ValueError

Table '{table_name}' not found in namespace '{self._namespac

Error message

Table '{table_name}' not found in namespace '{self._namespace}'.

What it means

CosmosTableProvider.read_dataframe queries documents whose table field matches table_name within the provider's namespace; if no documents match (and no legacy-migration path applies), the table simply does not exist and a ValueError is raised rather than returning an empty frame silently. The earlier branch returns a df when a legacy table is detected and a migration hint is logged.

Source

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

            async for doc in page:
                docs.append(_strip_cosmos_metadata(doc))  # noqa: PERF401

        if docs:
            return pd.DataFrame(docs)

        # ---- Legacy fallback (optional) --------------------------------
        if self._legacy_container is not None:
            df = await self._read_legacy_table(table_name)
            if df is not None and not df.empty:
                logger.warning(
                    "Reading '%s' from legacy container — run "
                    "'graphrag migrate-cosmos' to complete migration.",
                    table_name,
                )
                return df

        msg = f"Table '{table_name}' not found in namespace '{self._namespace}'."
        raise ValueError(msg)

    async def write_dataframe(self, table_name: str, df: pd.DataFrame) -> None:
        """Write *df* as documents, replacing any existing rows for this table."""
        container = await self._ensure_container()

        # Delete existing documents for this table in the namespace.
        await self._delete_table(container, table_name)

        records = json.loads(
            df.to_json(orient="records", lines=False, force_ascii=False)
        )
        docs = []
        for index, row in enumerate(records):
            row_key = row.pop("id", index)
            doc = {
                "id": f"{table_name}:{row_key}",
                "namespace": self._namespace,
                "table_name": table_name,

View on GitHub (pinned to f40e9a26ce)

Solutions

  1. Run (or re-run) the indexing pipeline so outputs are written before reading
  2. Verify database_name/container_name/namespace match the ones used at write time
  3. Check for typos in table_name against the pipeline's output table list

Example fix

# before
df = await provider.read_dataframe("create_base_entities")
# after
# index first: python -m graphrag index --root .
df = await provider.read_dataframe("create_base_entities")
Defensive patterns

Strategy: try-catch

Validate before calling

existing = {t for t in expected_tables if await provider.has_table(t)} if hasattr(provider, "has_table") else None

Try / catch

try:
    df = await provider.read_dataframe(name)
except ValueError as e:
    if "not found in namespace" in str(e):
        logger.warning("table %s missing; run indexing first", name)
        df = None
    else:
        raise

Prevention

When it happens

Trigger: Awaiting read_dataframe('create_base_entities') (or any output table) before the indexing pipeline has produced it, or with a different namespace/container than the one the outputs were written to.

Common situations: Running update/query against a fresh or wrong database; namespace mismatch after changing container_name or the namespace config; querying a table name that was renamed between GraphRAG versions.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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