zylon-ai/private-gpt · error · ValueError

Failed to inspect the database schema.

Error message

Failed to inspect the database schema.

What it means

ValueError raised inside DatabaseTableLikeInspector._extract_schema, the shared helper used by both the table and view inspectors. After _ensure_connected(), it calls inspect(self._engine) and treats a falsy result as a total inspection failure before reading columns, PK/FK constraints for the (schema, table_name) pair. Because this sits under both subclasses, one bad engine breaks every per-object extraction.

Source

Thrown at private_gpt/components/database/table_like_inspector.py:33

class DatabaseTableLikeInspector(DatabaseObjectInspector, ABC):
    @abstractmethod
    def get_objects(self, schema: str) -> list[InspectedDatabaseObject]:
        pass

    @abstractmethod
    def get_inspector_type(self) -> str:
        pass

    def _extract_schema(
        self, schema: str, table_name: str, obj_class: type[InspectedTableLike]
    ) -> InspectedTableLike:
        self._ensure_connected()
        meta = inspect(self._engine)

        if not meta:
            raise ValueError("Failed to inspect the database schema.")

        table_key = (schema, table_name)

        # Get columns
        multi_cols = meta.get_multi_columns(
            schema=schema, filter_names=[table_name], kind=obj_class.get_kind()
        )
        cols = multi_cols.get(table_key, [])

        # Get primary key
        multi_pks = meta.get_multi_pk_constraint(
            schema=schema, filter_names=[table_name], kind=obj_class.get_kind()
        )
        pk = multi_pks.get(table_key, {})

        # Get foreign keys
        multi_fks = meta.get_multi_foreign_keys(
            schema=schema, filter_names=[table_name], kind=obj_class.get_kind()

View on GitHub (pinned to 4a030776a3)

Solutions

1. Confirm the database is reachable and the engine can run a trivial query right before inspection
2. Retry once — transient drops between connect and inspect are the most common cause
3. Check SQLAlchemy/driver version compatibility (inspect() behavior changed across major versions)
4. In tests, patch inspect to return a real sqlalchemy.Inspector instead of None

Example fix

# before
def test_columns(engine):
    monkeypatch.setattr('sqlalchemy.inspect', lambda e: None)  # trips the guard

# after
from sqlalchemy import inspect as sa_inspect
monkeypatch.setattr('sqlalchemy.inspect', sa_inspect)

from sqlalchemy import inspect as sa_inspect, text

with engine.connect() as c:
    c.execute(text('SELECT 1'))
meta = sa_inspect(engine)
assert meta is not None  # mirrors the library's own guard

try:
    obj = inspector._extract_schema(schema, table_name, InspectedTable)
except ValueError as e:
    if 'Failed to inspect the database schema' in str(e):
        logger.warning('schema extraction failed for %s.%s; reconnecting', schema, table_name)
        engine.dispose()
        obj = inspector._extract_schema(schema, table_name, InspectedTable)
    else:
        raise

When it happens

Trigger: Any call that reaches _extract_schema — i.e. get_objects() on DatabaseTableInspector or DatabaseViewInspector, or direct extraction for a single table/view — while inspect(self._engine) returns falsy, typically because the engine is broken after the connection check passed.

Common situations: Connection dropped between _ensure_connected() and the inspect() call (transient network blip, idle timeout); driver incompatibility after a SQLAlchemy upgrade; mocked engines in unit tests; permissions revoked on the information schema mid-session.

Related errors

• Failed to inspect the database schema.
• Failed to inspect the database schema.
• One or more database connections failed: \n{errors}
• DB2 database query dependencies are not installed. Install w
• Cannot resolve SQLAlchemy engine for migration store '{store

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/11ac0a8ab78ed784. Report an issue: GitHub.