Pinecone: dimension and metric must match your embedding model, set once

TL;DR: Dimension must equal the embedding model's output width and metric must suit the embedding type. Both are frozen at index creation; a mismatch fails every write, and the only fix is recreating the index. Create a new index with the right dimension, re-embed, re-upsert.

Dimension and metric: get them right at creation, they are frozen

The rule

dimension must equal the number of floats your embedding model outputs. metric must suit how you compare them:

• cosine: normalized embeddings (most text models, e.g. OpenAI text-embedding-3). The common default.
• dotproduct: unnormalized embeddings, or sparse-only indexes.
• euclidean: when you genuinely need L2 distance.

Why agents get this wrong

The failure mode is creating the index first and choosing the embedding model later, or swapping models mid-project. text-embedding-3-small outputs 1536 dims; text-embedding-3-large outputs 3072; many open models output 768 or 1024. Upserting 768-dim vectors into a 1536-dim index fails every record with a dimension-mismatch error. There is no alter-index; you delete and recreate, then re-upsert everything.

Checklist before create_index

1. Decide the embedding model first. Print len(embedding) once and use that number.
2. Pick the metric from the list above, not from habit. If your vectors are L2-normalized, cosine and dotproduct agree; if they are not, they do not.
3. If you need sparse vectors (keyword signals), set vector_type appropriately at creation too.
4. Name the index after the model and dimension (e.g. docs-ada-1536) so a future agent can see the pairing without reading code.

If you already messed it up

Do not try to "fix" the vectors to fit (truncating or padding silently destroys recall). Create a new index with the right dimension, re-embed, re-upsert. For large indexes use the bulk import path rather than re-upserting one by one.

When to use this

• This covers exactly what the title says: Pinecone.
• You are setting this up for the first time, or auditing an existing setup.
• You want the key gotchas in one place before you start.

When not to use this

• You are doing a different workflow with Pinecone; these steps are specific to the title above.
• You need the full reference docs; this is the short path, not the manual.

Compatibility

• Not pinned to a specific version; follows current Pinecone behavior.

Pinecone's create-an-index guide states dimension, metric, and vector type are set at creation and shows the supported metrics. The limits reference caps dense dimensionality at 20,000. The embedding-changed troubleshooting page covers float handling on upsert. Verified against live docs 2026-09-26.