MemPalace/mempalace · critical · DimensionMismatchError

collection was built with a {stored.dimension}-dim embedder

Error message

collection was built with a {stored.dimension}-dim embedder ({stored.model_name!r}) but the current embedder is {current.dimension}-dim ({current.model_name!r}); the stored vectors are incompatible. Re-embed the palace to switch models.

What it means

Raised as RebuildCollectionError (live_replaced=True) when a collection rebuild already deleted the old live collection and swapped in a new one, but re-uploading the extracted rows into the new collection then failed. The pre-swap copy still exists under the temp collection name and is the only verified copy of the data. The code deliberately does NOT delete the temp collection on this path because doing so would destroy the last recoverable copy.

Source

Thrown at mempalace/backends/base.py:233

    """
    if current is None or not current.model_name:
        return "unknown"
    if stored is None:
        return "unknown"

    dim_conflict = bool(stored.dimension and current.dimension) and (
        stored.dimension != current.dimension
    )
    name_conflict = stored.model_name != current.model_name

    if not dim_conflict and not name_conflict:
        return "known_match"

    if force_model_swap:
        return "known_mismatch"

    if dim_conflict:
        raise DimensionMismatchError(
            f"collection was built with a {stored.dimension}-dim embedder "
            f"({stored.model_name!r}) but the current embedder is "
            f"{current.dimension}-dim ({current.model_name!r}); the stored "
            "vectors are incompatible. Re-embed the palace to switch models."
        )
    raise EmbedderIdentityMismatchError(
        f"collection was built with embedder {stored.model_name!r} but the "
        f"current embedder is {current.model_name!r}. Searching across a model "
        "swap silently degrades recall. Re-embed the palace, or run "
        "`mempalace palace set-embedder --model <name> --force` to record the "
        "new identity if you know the vectors are compatible."
    )


@dataclass(frozen=True)
class HealthStatus:
    ok: bool
    detail: str = ""

View on GitHub (pinned to 06cb6987f0)

Solutions

Do NOT delete the temp collection named in the message — it is the only intact verified copy.
Remove the broken '{collection_name}' collection via the backend (e.g. chroma client.delete_collection).
Re-run the rebuild/promotion so '{temp_name}' is promoted into '{collection_name}', or manually rename it in the backend.
Investigate the original {exc} (disk space, chromadb logs) before retrying the upload so the retry does not fail the same way.

Defensive patterns

Strategy: try-catch

Try / catch

try:
    rebuild_collection(...)
except RebuildCollectionError as e:
    if e.live_replaced:
        # temp collection is the ONLY copy — promote it, never delete
        promote_temp_collection(backend, palace_path, temp_name)
    else:
        # safe to clean up and retry
        retry_rebuild()

Prevention

Verify free disk space and chromadb health before starting a rebuild.
Take a palace backup before any rebuild command.
Treat live_replaced=True errors as recovery operations, not failures to retry blindly.

When it happens

Trigger: Calling the rebuild-collection path in mempalace/repair.py when the upsert/re-upload stage raises after the swap stage completed (live_replaced is True). Any exception during the re-upload into the freshly-promoted '{collection_name}' collection hits this handler.

Common situations: Disk filling up mid-upload, chromadb raising on a bad embedding dimension or corrupted segment, or the process being interrupted after the swap point. Operators who assume the error means 'total loss' and delete everything, including '{temp_name}', make it unrecoverable.

Related errors

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