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 DatabaseViewInspector.get_objects, the view-side twin of the table inspector: if inspect(self._engine) is falsy it aborts before meta.get_view_names(schema=schema). Identical defensive guard, identical meaning — the engine could not be introspected at all, and the generic message hides the root cause.

Source

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

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


class DatabaseViewInspector(DatabaseTableLikeInspector):
    def get_inspector_type(self) -> str:
        return DatabaseObjectType.VIEW

    def get_objects(self, schema: str) -> list[InspectedDatabaseObject]:
        meta = inspect(self._engine)
        if not meta:
            raise ValueError("Failed to inspect the database schema.")
        views = sorted(meta.get_view_names(schema=schema))
        result: list[InspectedDatabaseObject] = []

        for view_name in views:
            result.append(self._extract_schema(schema, view_name, InspectedView))

        return result

View on GitHub (pinned to 4a030776a3)

Solutions

1. Test the engine with a trivial query before calling get_objects
2. Restore/verify connectivity (database up, credentials valid, network reachable) and retry
3. Align SQLAlchemy and DB driver versions if inspection broke after an upgrade
4. Use a real Inspector (or a faithful fake) in tests instead of None

Example fix

# before
views = view_inspector.get_objects('public')  # ValueError: Failed to inspect the database schema.

# after
with engine.connect() as c:
    c.execute(text('SELECT 1'))
views = view_inspector.get_objects('public')

from sqlalchemy import text

with engine.connect() as c:
    c.execute(text('SELECT 1'))  # catch dead engines before view listing

try:
    views = view_inspector.get_objects(schema)
except ValueError as e:
    if str(e) == 'Failed to inspect the database schema.':
        engine.dispose()  # recycle pool, then one retry
        views = view_inspector.get_objects(schema)
    else:
        raise

When it happens

Trigger: Calling get_objects(schema) on a DatabaseViewInspector with a dead or misconfigured engine, so inspect() yields nothing before view names are enumerated.

Common situations: Same class of issues as the table inspector: dropped connections, wrong DSN, driver/SQLAlchemy mismatch, or test doubles returning falsy inspectors. Shows up when only the view listing is exercised (e.g. UI tab that lists views first).

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