MemPalace/mempalace · warning · UnsupportedMaintenanceKindError

pgvector does not support maintenance kind {kind!r}

Error message

pgvector does not support maintenance kind {kind!r}

What it means

run_maintenance() only accepts the maintenance kinds declared in PgVectorBackend.maintenance_kinds (e.g. "analyze"). Any other kind string raises UnsupportedMaintenanceKindError before touching the database, per the pluggable-backend maintenance contract in backends/base.py.

Source

Thrown at mempalace/backends/pgvector.py:1294

        try:
            if not self._table_exists():
                return empty
            rows = self._client.count_rows(self._table)
            has_index = self._client.has_vector_index(self._table)
        except Exception:  # noqa: BLE001 - state report must not raise
            logger.debug("pgvector maintenance state probe failed", exc_info=True)
            return empty
        return {
            "row_count": rows,
            "vector_index": "hnsw" if has_index else None,
            "index_build_complete": has_index,
        }

    def run_maintenance(self, kind: str):
        from .base import MaintenanceResult, UnsupportedMaintenanceKindError

        if kind not in PgVectorBackend.maintenance_kinds:
            raise UnsupportedMaintenanceKindError(
                f"pgvector does not support maintenance kind {kind!r}"
            )
        self._ensure_open()
        # Nothing to maintain on a not-yet-materialized table (collection opened
        # create=True but never written) — return noop rather than letting a
        # raw "relation does not exist" error escape.
        if not self._table_exists():
            return MaintenanceResult(kind=kind, status="noop", stats={"reason": "no table"})
        if kind == "analyze":
            self._client.analyze_table(self._table)
            return MaintenanceResult(kind="analyze", status="ran")

        # reindex → build the optional HNSW index. Opt-in: it makes search
        # approximate, trading the exact-scan 100%-recall default for scale.
        # Serialized with a session advisory lock so concurrent daemon writers
        # learn "already_running" instead of each stacking an ACCESS EXCLUSIVE
        # index build.
        if self._client.has_vector_index(self._table):

View on GitHub (pinned to 06cb6987f0)

Solutions

1. Check PgVectorBackend.maintenance_kinds (or the backend's describe output) before calling run_maintenance.
2. Only request kinds the backend declares; for pgvector that is "analyze".
3. Catch UnsupportedMaintenanceKindError in generic tooling and skip/report that kind for this backend.

Example fix

# before
backend.run_maintenance("vacuum")

# after
if "analyze" in PgVectorBackend.maintenance_kinds:
    backend.run_maintenance("analyze")

kinds = getattr(backend, "maintenance_kinds", ())
results = [backend.run_maintenance(k) for k in requested if k in kinds]

def supports_maintenance(backend, kind: str) -> bool:
    return kind in getattr(backend, "maintenance_kinds", ())

from mempalace.backends.base import UnsupportedMaintenanceKindError
try:
    backend.run_maintenance(kind)
except UnsupportedMaintenanceKindError:
    logger.info("skipping %s on %s", kind, backend.name)

When it happens

Trigger: Calling run_maintenance("vacuum"), run_maintenance("reindex"), or any kind the pgvector backend has not implemented; passing a kind valid on a different backend (e.g. one ChromaDB supports) to pgvector.

Common situations: Generic maintenance scripts that iterate a hard-coded list of kinds across all backends; copying a maintenance call from a ChromaDB deployment to a pgvector one.

Related errors

• facet_counts does not support local-only filters
• pgvector backend requires a local palace path to anchor mism
• {label} length {len(value)} does not match ids length {n}
• pgvector requires query_embeddings; use palace.get_collectio
• query requires query_embeddings

AI-assisted analysis of MemPalace/mempalace@06cb6987f0 (2026-08-15). Data as JSON: /api/errors/63b868be501d8c2c. Report an issue: GitHub.