TL;DR — A dimension mismatch means you sent a vector of one length into an index built for another, which happens the moment you change embedding model. There is no compatibility shim: vectors from different models are not comparable even at equal length. You either re-embed the corpus with the new model, or stay on the old one. Some newer models support a shortened output dimension, which lets you fit an existing index — but only if the index was built with that same model at that same length.
The error
The wording varies by store, the cause does not:
Vector dimension 1536 does not match the dimension of the index 3072
expected 1536 dimensions, not 768
ERROR: expected 1536 dimensions, not 3072 -- pgvector
It appears at insert time, right after someone swaps the embedding model — often in a config file, by someone who did not realise the index was coupled to it.
Why dimensions differ
Each embedding model emits a fixed-length vector, and the length is a property of the model. Different models, different lengths. An index is created with one length and cannot hold another.
The deeper point, which matters more than the error: two models' vectors are not interchangeable even when the lengths happen to match. Each model has its own geometry — "similar" means something different in each space. Mixing them in one collection produces no error at all and quietly ruins your retrieval quality, which is a far worse outcome than a failed insert. The dimension check is doing you a favour by failing loudly.
Your two options
Option A — re-embed everything (the correct one). Create a new index with the new model's dimension, re-embed the whole corpus, verify retrieval quality, then cut over.
old index (model A) ──> keep serving
new index (model B) ──> backfill, verify, then switch reads
Do it as a backfill-then-switch, not an in-place migration: keeping the old index live means a bad result on the new model is a rollback instead of an outage. Cost is one full pass of embedding your corpus — usually the cheapest part of a RAG stack, and worth budgeting before you decide to switch models rather than discovering it mid-migration.
Option B — shortened dimensions. Some newer embedding models can emit a shorter vector than their native length, which lets a larger model fit a smaller index. This is useful for storage and speed, but it does not make model A's vectors compatible with model B's — it only changes the length. Truncating to match an existing index built with a different model gives you an index that accepts the writes and returns bad neighbours.
What is not a fix
- Padding or truncating to match. The vector is not "too long"; it is from a different space.
- Mixing models in one collection. No error, silently degraded retrieval — the most expensive version of this mistake.
- Changing the declared dimension on an existing index. Where a store even allows it, existing vectors do not change.
Prevention
- Store the embedding model id and dimension as metadata on the index, and assert on it before every write. This turns a silent quality regression into a loud failure.
- Treat the embedding model as part of the index identity — name the collection after it (
docs_v2_modelB_1536), so switching models is obviously a new index rather than a config tweak. - Pin the model version. Retrieval quality drifting after an unpinned model update is much harder to diagnose than a dimension error, because nothing fails.
- Changing models across providers is easier when the swap is a routing decision rather than a code change — related: AI API gateway vs LLM router.