Skip to content
Underread
Guides

How to Fix “Vector dimension does not match the dimension of the index” in Pinecone

The 2 numbers in the error tell you everything. One is your embedding model, the other is a decision you made when you created the index.

By Vemuri Abhiram6 min read
Abstract grid of glowing points representing a vector space
Abstract grid of glowing points representing a vector space
On this page

Your retrieval pipeline worked last week. You swapped the embedding model, re-ran the ingest, and every upsert now fails:

PineconeApiException: Vector dimension 768 does not match
the dimension of the index 1536

The good news is that this is one of the clearest errors you'll ever get. It names both numbers, and between them they tell you exactly what happened.

#What the 2 numbers mean

In the message What it is Where it comes from
"Vector dimension 768" The embedding you just produced Your model
"dimension of the index 1536" What the index was built for create_index

#1. Confirm which side moved

Before you change anything, check what the index actually expects and what your model is actually producing, because assuming either one wastes time. Both are a single call away:

print(index.describe_index_stats())      # what the index wants
print(len(embed("a test sentence")))     # what you are sending

Nearly always the index is unchanged and the model moved, because an index dimension can't be edited after creation — if it were different from last week, somebody recreated it deliberately. Common embedding sizes cluster around a handful of values, so recognising them speeds up the diagnosis: 384 and 768 are typical of smaller open models, while 1536 and 3072 are typical of larger hosted ones.

#2. The usual cause, and the ones people miss

Switching model is the obvious cause and the one you'll hit most. The subtler versions are worth knowing because they produce the identical error without anybody consciously changing anything.

A default changed under you. A framework upgrade that moves its default embedding model, a configuration value read from an environment that differs between your laptop and CI, or a model alias that now points somewhere new. The code looks untouched and the output size isn't.

Two paths through the same system. Ingest uses one model and query uses another. The upsert succeeds and the query fails, which sends people hunting in entirely the wrong place because the error appears at query time.

A truncated or configurable model. Some embedding models accept a dimension parameter and will happily return a shortened vector. If that parameter is set in one place and not another, you get 2 different sizes from what is nominally the same model.

#3. Pick a fix, and know what it costs

There are only 2 real options, and the choice is about which cost you'd rather pay rather than which is technically better.

Recreate the index at the new dimension. This is right when you moved model deliberately and want to keep the new one. The cost is real: you have to re-embed every document you've already ingested, which takes time and money proportional to your corpus, and the index is empty until you've finished. Create the new index alongside the old one, backfill it, switch the read path, and only then delete the old one — a cutover rather than an outage.

pc.create_index(
    name="docs-v2",
    dimension=768,
    metric="cosine",
    spec=ServerlessSpec(cloud="aws", region="us-east-1"),
)

Go back to the original model. This is right when the change was accidental. It costs nothing, takes a minute, and keeps your existing vectors valid. Pin the model name explicitly rather than relying on a default, so the same accident can't recur.

What you cannot do is mix. Vectors from 2 different models in 1 index are meaningless even when the dimensions happen to match, because similarity between them is noise. If you've already upserted some of each, the index is poisoned and re-embedding is the only honest fix.

#4. Stop it recurring

Assert the dimension at startup, where the failure is loud, cheap and happens before any data is written:

EXPECTED = 768

def check(index, embed):
    want = index.describe_index_stats()["dimension"]
    got = len(embed("startup check"))
    if not (want == got == EXPECTED):
        raise SystemExit(f"dimension mismatch: index={want} model={got}")

Pin the embedding model name in configuration, never a floating alias, and store it in the index metadata or the name itself. An index called docs-v2-768 tells the next person what it holds without them having to work it out from an error message.

#5. Plan the cutover before you start

Recreating an index sounds like a 1-line change. It isn't. I've done this on a corpus of about 40,000 chunks and the re-embedding ran for most of an afternoon.

Budget for it properly. Work out your chunk count, multiply by the new model's cost per token, and check the number before you commit rather than after. Then run the backfill against a new index while the old one keeps serving queries, so nobody notices anything. Switch the read path only when the new index is complete, and keep the old one for a day in case you need to switch back.

The temptation is to delete the old index first to save on storage. Don't. A day of duplicate storage costs very little, and it's the only thing standing between you and an empty search box if the backfill turns out to have a bug in it.

#6. Name things so the next person can't get this wrong

Put the dimension in the index name. Not in a comment. In the name.

docs-v2-768 answers the question before anyone has to ask it, and it makes a mismatch obvious at a glance rather than at upsert time. Store the model name alongside it, in the index metadata or in your own configuration, because 6 months from now the dimension alone won't tell you which 768-dimension model produced these vectors, and that matters the moment you want to add more.

#Match your symptom to the fix

What you're seeing Likely cause Go to
Started after changing model Deliberate switch 3
Started after a library upgrade Default model moved 2
Upserts fine, queries fail 2 models in 1 pipeline 2
Works locally, fails in CI Different configuration 2
Numbers differ by a factor of 2 Truncation parameter set somewhere 2

#When the numbers match and it still fails

If both sides report the same dimension and upserts still fail, look at the shape of what you're sending rather than its length. A nested list, a list of lists where a flat list is expected, or a numpy array that hasn't been converted to a plain list are all common, and the resulting message can be misleading.

print(type(vec), len(vec), type(vec[0]))

You want a flat sequence of floats. If vec[0] is itself a list, you're sending a batch where a single vector was expected — a different bug entirely, wearing this error's clothes. If you're still building the retrieval layer, the context length guide covers the chunking decisions that tend to cause the next problem after this one.

Frequently asked questions

Can I change an index's dimension after creating it?

No. The dimension is fixed at creation, which is why the fix is always to create a new index rather than to alter the existing one.

Do I really have to re-embed everything?

Yes, if you're keeping the new model. Vectors from different models aren't comparable, so old ones can't be carried across even when the dimension happens to line up.

Is a higher dimension better?

Not automatically. Larger vectors cost more to store and search, and the gain in retrieval quality is often small for ordinary document search. Test both on your own data before assuming.

What if I need 2 embedding models?

Use 2 indexes. That's the supported shape, it keeps each set of vectors comparable, and it makes the separation obvious to whoever reads the code next.

Written by

Vemuri Abhiram

Founder & Editor

Vemuri Abhiram is the founder and editor of Underread, where he writes about AI tools, software, and practical technology. He covers hands-on tool reviews, detailed guides, product comparisons, and emerging technologies.

More from Underread, once a week.

The guides worth reading and the tests worth trusting. One email, every Friday.

No spam. Unsubscribe in one click.