zylon-ai/private-gpt · error · ImportError

Postgres client dependencies are not installed. Install with

Error message

Postgres client dependencies are not installed. Install with one of: `uv sync --inexact --extra database-postgres` or `uv sync --inexact --extra nodestore-postgres`.

What it means

Module-level import guard in postgres_client.py: at import time it uses `find_spec` to check for `psycopg2` and `sqlalchemy`; if either is absent it raises ImportError with an install hint naming the `database-postgres` and `nodestore-postgres` extras. Because it runs at import, merely importing this module (transitively, when postgres is configured) fails in environments missing the optional deps.

Source

Thrown at private_gpt/components/postgres/postgres_client.py:8

import logging
import threading
from importlib.util import find_spec

from private_gpt.utils.dependencies import format_missing_dependency_message

if find_spec("psycopg2") is None or find_spec("sqlalchemy") is None:
    raise ImportError(
        format_missing_dependency_message(
            "Postgres client",
            extras=("database-postgres", "nodestore-postgres"),
        )
    )

from sqlalchemy import create_engine
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.orm import Session, sessionmaker

from private_gpt.settings.settings import Settings

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)


class PostgresClient:
    def __init__(self, settings: Settings):

View on GitHub (pinned to 4a030776a3)

Solutions

Install the extra: `uv sync --inexact --extra database-postgres` (or `nodestore-postgres` if only node store needs it)
If psycopg2 binary wheels are a problem on your platform, install `psycopg2-binary` or build deps accordingly
Keep the provider setting consistent with installed extras to avoid importing this module unconditionally

Example fix

# before
uv sync --inexact
# settings: database.provider=postgres -> ImportError

# after
uv sync --inexact --extra database-postgres

Defensive patterns

Strategy: validation

Validate before calling

from importlib.util import find_spec

if settings.database.provider == "postgres" or settings.node_store.index_store == "postgres":
    missing = [m for m in ("psycopg2", "sqlalchemy") if find_spec(m) is None]
    if missing:
        raise SystemExit(f"missing {missing}; run: uv sync --inexact --extra database-postgres")

Try / catch

try:
    from private_gpt.components.postgres import postgres_client
except ImportError as e:
    raise SystemExit(str(e)) from e  # surfaces the exact uv sync command

Prevention

Install extras in lockstep with settings changes; put both in the same PR
Add CI matrix jobs covering each extras combination you deploy

When it happens

Trigger: Configuring postgres as database provider or node store in an environment installed without the extras; any code path importing `private_gpt.components.postgres.postgres_client` (e.g. persistence component's postgres branch, node store's postgres provider) triggers the check at import.

Common situations: Minimal installs (`uv sync` without extras) then flipping settings to postgres; slim Docker images; CI jobs testing non-postgres paths that accidentally import the module.

Related errors

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