{"record":{"id":"aeefaa81a78a8da3","repo":"zylon-ai/private-gpt","slug":"failed-to-inspect-the-database-schema","errorCode":null,"errorMessage":"Failed to inspect the database schema.","messagePattern":"Failed to inspect the database schema\\.","errorType":"exception","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"private_gpt/components/database/table_inspector.py","lineNumber":20,"sourceCode":"\nfrom private_gpt.components.database.inspected_schema import InspectedTable\nfrom private_gpt.components.database.inspector_interface import (\n    DatabaseObjectType,\n    InspectedDatabaseObject,\n)\nfrom private_gpt.components.database.table_like_inspector import (\n    DatabaseTableLikeInspector,\n)\n\n\nclass DatabaseTableInspector(DatabaseTableLikeInspector):\n    def get_inspector_type(self) -> str:\n        return DatabaseObjectType.TABLE\n\n    def get_objects(self, schema: str) -> list[InspectedDatabaseObject]:\n        meta = inspect(self._engine)\n        if not meta:\n            raise ValueError(\"Failed to inspect the database schema.\")\n        tables = sorted(meta.get_table_names(schema=schema))\n        result: list[InspectedDatabaseObject] = []\n        for table_name in tables:\n            result.append(self._extract_schema(schema, table_name, InspectedTable))\n        return result\n","sourceCodeStart":2,"sourceCodeEnd":26,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/components/database/table_inspector.py#L2-L26","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify connectivity with the same engine first: engine.connect() and run SELECT 1","Check the server is up and credentials/URL are correct, then retry the inspection","If you are mocking the engine in tests, make inspect() return a real Inspector-like object (the falsy return is what trips this guard)","Wrap the call and capture logs — the real failure detail is logged upstream of this generic guard"],"exampleFix":"# before\ninspector = DatabaseTableInspector(engine)\ntables = inspector.get_objects('public')  # ValueError\n\n# after\nwith engine.connect() as c:\n    c.execute(text('SELECT 1'))  # fail early with the real error\ntables = inspector.get_objects('public')","handlingStrategy":"try-catch","validationCode":"from sqlalchemy import text\n\nwith engine.connect() as c:\n    c.execute(text('SELECT 1'))  # surfaces real connectivity issues first","typeGuard":null,"tryCatchPattern":"try:\n    tables = table_inspector.get_objects(schema)\nexcept ValueError as e:\n    if str(e) == 'Failed to inspect the database schema.':\n        # generic guard: re-check connectivity and retry once\n        with engine.connect() as c:\n            c.execute(text('SELECT 1'))\n        tables = table_inspector.get_objects(schema)\n    else:\n        raise","preventionTips":["Pre-flight a trivial query on the engine before schema inspection","Use connection pooling with pre-ping so dead connections are evicted","Never mock sqlalchemy.inspect to return None in tests"],"tags":["database","sqlalchemy","schema-introspection","connection"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}