zylon-ai/private-gpt · error · ImportError

Postgres node store dependencies are not installed. Install

Error message

Postgres node store dependencies are not installed. Install with `uv sync --inexact --extra nodestore-postgres`.

What it means

Import-time guard in `_postgres_index_store`: the `PostgresIndexStore` / patched KV store imports are wrapped in try/except ImportError, and on failure it raises ImportError with a formatted install hint naming the `nodestore-postgres` extra. It means the Python environment lacks the optional Postgres storage dependencies (psycopg2, sqlalchemy, llama-index postgres storage).

Source

Thrown at private_gpt/components/node_store/node_store_component.py:51

        return SimpleIndexStore.from_persist_dir(
            persist_dir=str(local_data_path / collection)
        )
    except FileNotFoundError:
        logger.debug("Local index store not found, creating a new one")
        return SimpleIndexStore()


def _postgres_index_store(settings: Settings, collection: str) -> BaseIndexStore:
    try:
        from llama_index.storage.index_store.postgres import (  # ty:ignore[unresolved-import]
            PostgresIndexStore,
        )

        from private_gpt.components.node_store.patched_postgres_kv_store import (
            PatchedPostgresKVStore,
        )
    except ImportError as e:
        raise ImportError(
            format_missing_dependency_message(
                "Postgres node store",
                extras="nodestore-postgres",
            )
        ) from e

    from private_gpt.components.postgres.postgres_client import LazyPostgresFactory

    client = LazyPostgresFactory.get_instance(settings)
    kv_store = PatchedPostgresKVStore(
        client.sync_session,
        client.async_session,
        table_name=collection,
        schema_name="zgptnode",
    )
    return typing.cast(BaseIndexStore, PostgresIndexStore(kv_store))

View on GitHub (pinned to 4a030776a3)

Solutions

Install the extra exactly as the message says: `uv sync --inexact --extra nodestore-postgres`
Or switch `node_store.index_store` back to a provider whose deps are installed (e.g. simple) if Postgres was unintended
Rebuild the deployment image including the extra

Example fix

# before
uv sync --inexact
# node_store.index_store: postgres -> ImportError

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

Defensive patterns

Strategy: validation

Validate before calling

from importlib.util import find_spec

missing = [m for m in ("psycopg2", "sqlalchemy") if find_spec(m) is None]
if missing and settings.node_store.index_store == "postgres":
    raise SystemExit("Run: uv sync --inexact --extra nodestore-postgres")

Try / catch

try:
    store = node_store.index_store(collection)
except ImportError as e:
    if "nodestore-postgres" in str(e):
        raise SystemExit(str(e))  # fail fast with the install command
    raise

Prevention

Encode required extras in deployment scripts/Dockerfile next to the settings that need them
Add a startup preflight that checks find_spec for every optional dep implied by settings

When it happens

Trigger: Setting `node_store.index_store` to a Postgres-backed provider while the package was installed without the `nodestore-postgres` extra; deploying with a trimmed dependency set; CI environments using `--no-deps` or minimal extras.

Common situations: Fresh deploy where settings.yaml enables postgres node store but requirements only include core deps; Docker images built with only default extras; upgrading and switching from simple/none store to postgres without re-syncing env.

Related errors

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