zylon-ai/private-gpt · error · ValueError

Migration client is not available for store '{store}'

Error message

Migration client is not available for store '{store}'

What it means

`apply_migrations` (guarded by a lock and an idempotency flag) resolves the client via `self.get_client(store)`; a None return raises `ValueError` saying no migration client is available for the configured provider. In practice `get_client` returns None only when the `match store` in `get_client` falls through without assigning — i.e. a provider value handled by neither the postgres nor sqlite branch.

Source

Thrown at private_gpt/components/persistence/persistence_component.py:91

                raise ValueError(f"Unsupported store type: {store}")

    def apply_migrations(self) -> None:
        with self._lock:
            if self._migrations_applied:
                logger.info("Migrations already applied in this process; skipping")
                return

            store = self._settings.database.provider
            schema = self._settings.database.schema_name
            logger.info(
                "Applying migrations with provider=%s schema=%s total=%s",
                store,
                schema,
                len(MIGRATIONS),
            )
            client = self.get_client(store)
            if client is None:
                raise ValueError(
                    f"Migration client is not available for store '{store}'"
                )

            migration_backend: MigrationBackend = self._get_migration_backend(
                store=store,
                client=client,
            )
            runner = MigrationRunner(migration_backend)
            runner.run_up(migrations=list(MIGRATIONS))
            self._migrations_applied = True
            logger.info("Migrations applied successfully")

    # Testing use: This method will revert all migrations
    def revert_migrations(self) -> None:
        with self._lock:
            store = self._settings.database.provider
            schema = self._settings.database.schema_name
            logger.info(

View on GitHub (pinned to 4a030776a3)

Solutions

1. Set `database.provider` to a value supported by `get_client` ('postgres' or 'sqlite')
2. Fix typos/casing in the provider setting
3. If extending with a new store, implement both the client branch and the migration backend branch so `get_client` never returns None

client = persistence.get_client(settings.database.provider)
if client is None:
    raise ValueError(
        f"no client for provider {settings.database.provider!r}; expected postgres or sqlite"
    )

try:
    persistence.apply_migrations()
except ValueError as e:
    if "Migration client is not available" in str(e):
        raise SystemExit(f"fix database.provider: {e}") from e
    raise

When it happens

Trigger: Startup with `database.provider` set to an unrecognized value: `get_client`'s match falls through, caches nothing, returns None, and `apply_migrations` raises; also possible if a custom store branch returns None explicitly.

Common situations: Provider typos (e.g. 'none', 'postgres '); config drift between what `get_client` supports and what callers assume; environment-specific overrides with stale provider names.

Related errors

• local_path is required for sqlite client
• Unsupported store type: {store}
• Default LLM model '{model_id}' could not be initialized: {e}
• Default model '{self._default_model_id}' not found in regist
• No model specified and no models are configured

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