# wrangler vectorize insert failed: dimension mismatch

## TL;DR

The vectors being inserted do not match the index's configured dimensions. Check the embedding model's output size vs the index config; they must agree exactly. Regenerate or reconfigure so they match.

```text
wrangler vectorize insert failed: dimension mismatch
```

## Steps

1. Check the index's configured dimensions and the vector length being inserted.
   Expected: The mismatch is quantified.

2. Find the source: the embedding model changed, or the wrong model is called.
   Expected: The model and index disagree.

3. Fix by aligning them: re-create the index with the model's dimensions, or switch to the model the index expects.
   Expected: They match.

4. Re-insert the vectors.
   Expected: Inserts succeed.

5. Pin the embedding model version and assert dimensions at insert time.
   Expected: Drift is caught immediately.

## When to use

- vectorize inserts fail on dimension mismatch
- the embedding model changed
- the index was created for a different model

## When not to use

- dimensions match (check the actual inserted length)
- the error is on metadata (different issue)
- using a different vector DB (same concept, different config)

## Tool compatibility

- wrangler
- Cloudflare Vectorize

## Variant phrasings

- "vectorize dimension mismatch"
- "vector insert dimension error"
- "embedding dimension mismatch index"

## Why it happens

Vector indexes are built for a fixed dimensionality; the math does not work across sizes. Model upgrades often change dimensions silently (or the code calls a different model than the index was built for). The insert is where the disagreement surfaces, but the cause is the model/index pairing.

## Edge cases

- re-creating the index loses existing vectors; plan the migration
- the assertion belongs in the insert path, not just in tests
- model version pins need to cover the tokenizer too, not just the weights

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_4rPetCDnCGNfb3AA-RZ-UA