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 in DatabaseTableInspector.get_objects when SQLAlchemy's inspect(engine) returns a falsy value before table names are listed. SQLAlchemy normally always returns an Inspector object, so a falsy result in practice means engine inspection failed outright (broken engine, dropped connection, unusable dialect). The check is a defensive guard, and the message does not include the underlying cause.

Source

Thrown at private_gpt/components/database/table_inspector.py:20

from private_gpt.components.database.inspected_schema import InspectedTable
from private_gpt.components.database.inspector_interface import (
    DatabaseObjectType,
    InspectedDatabaseObject,
)
from private_gpt.components.database.table_like_inspector import (
    DatabaseTableLikeInspector,
)


class DatabaseTableInspector(DatabaseTableLikeInspector):
    def get_inspector_type(self) -> str:
        return DatabaseObjectType.TABLE

    def get_objects(self, schema: str) -> list[InspectedDatabaseObject]:
        meta = inspect(self._engine)
        if not meta:
            raise ValueError("Failed to inspect the database schema.")
        tables = sorted(meta.get_table_names(schema=schema))
        result: list[InspectedDatabaseObject] = []
        for table_name in tables:
            result.append(self._extract_schema(schema, table_name, InspectedTable))
        return result

View on GitHub (pinned to 4a030776a3)

Solutions

1. Verify connectivity with the same engine first: engine.connect() and run SELECT 1
2. Check the server is up and credentials/URL are correct, then retry the inspection
3. If you are mocking the engine in tests, make inspect() return a real Inspector-like object (the falsy return is what trips this guard)
4. Wrap the call and capture logs — the real failure detail is logged upstream of this generic guard

Example fix

# before
inspector = DatabaseTableInspector(engine)
tables = inspector.get_objects('public')  # ValueError

# after
with engine.connect() as c:
    c.execute(text('SELECT 1'))  # fail early with the real error
tables = inspector.get_objects('public')

from sqlalchemy import text

with engine.connect() as c:
    c.execute(text('SELECT 1'))  # surfaces real connectivity issues first

try:
    tables = table_inspector.get_objects(schema)
except ValueError as e:
    if str(e) == 'Failed to inspect the database schema.':
        # generic guard: re-check connectivity and retry once
        with engine.connect() as c:
            c.execute(text('SELECT 1'))
        tables = table_inspector.get_objects(schema)
    else:
        raise

When it happens

Trigger: Calling get_objects(schema) on a DatabaseTableInspector whose engine is misconfigured or whose database connection has died, so that inspect(self._engine) yields nothing usable before meta.get_table_names(schema=schema) is attempted.

Common situations: Database restarted or network dropped between connect and inspection; wrong credentials/dialect leaving the engine in a bad state; testing with a mock/fake engine that returns None from inspect(); driver-level failure on exotic databases.

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/aeefaa81a78a8da3. Report an issue: GitHub.