> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/troubleshooting/dimension-mismatches.md).

# Dimension mismatches

Fix embedding dimension errors — dim vs profile.dimension at create, query length vs dim at search, and space\_id incompatibility after changing models.

Telys is strict about vector width: a collection stores fixed-width vectors, and every vector you add or query must match. A mismatch raises a clear `ValueError` or `AssertionError` at the point of failure rather than silently corrupting results. It shows up in three places — at create, at search, and after you change embedding models.

{% hint style="info" %}
A collection's width comes from its embedder's `EmbeddingProfile.dimension`. Create the collection with `dim=emb.profile.dimension` and you'll never have to guess a number.
{% endhint %}

## Errors and fixes

<details>

<summary><code>dim</code> doesn't match the embedder profile at <code>create_collection</code></summary>

`create_collection(name, dim, ...)` fixes the collection width. Pass an embedder whose `profile.dimension` differs from `dim`, and `create_collection` itself raises — `ValueError: embedder dim X != collection dim Y` — before any insert runs. A wrong-width vector batch fails later, at ingest: `add`/`upsert` raises `ValueError: vectors must be (n, dim); got shape ...`. `CallableEmbedder` is especially strict: it asserts every batch is 2-D and `shape[1] == profile.dimension`.

**Cause:** a hard-coded `dim` that doesn't equal the embedder's real dimension. `Algenta*` embedder dims are read from the native kernel (64 and 384 are hints, not guaranteed constants), so hard-coding them is fragile.

**Fix:** always derive `dim` from the profile.

```python
from telys import Telys
from telys.embedding import AlgentaMultigramEmbedder

emb = AlgentaMultigramEmbedder()
mem = Telys("./memory")
col = mem.create_collection(
    "notes",
    dim=emb.profile.dimension,     # not a hard-coded 384
    partition_by="scope",
    embedder=emb,
)
```

For `CallableEmbedder`, the wrapped function must return exactly `profile.dimension` columns, or its assertion fires on the first add.

</details>

<details>

<summary><code>ValueError</code> — query vector length doesn't equal the collection dim</summary>

`search(vector, ...)` validates `len(vector) == dim` before it runs, so a query of the wrong width fails immediately.

**Cause:** the query vector was built with a different model (or a truncated/padded array) than the collection.

**Fix:** embed the query with the **same** embedder as the collection, or check the width before calling `search`.

```python
# Preferred: let the collection embed the query with its own embedder
col.search_text("how do refunds work", top_k=5)

# If you pass a raw vector, it must match the collection width exactly:
import numpy as np
q = np.asarray(query_vector, dtype="float32")
assert q.shape[-1] == emb.profile.dimension     # same width the collection was built with
res = col.search(q, top_k=5)
```

`search_text` avoids length errors entirely — the collection's own embedder produces the query vector.

</details>

<details>

<summary>Changed the embedding model — new <code>space_id</code>, incompatible collection</summary>

A collection is bound to a **vector space**, identified by the embedder's `EmbeddingProfile.space_id()` — a SHA-256 over provider, model id, version, dimension, normalization, distance, and pooling. Change any of those and the `space_id` changes, so vectors from the new model are not comparable to the old ones. `profile.compatible_with(other)` is simply `space_id` equality.

**Cause:** you swapped embedders (or bumped a model version) and queried or added into a collection built in a different space.

**Fix:** a space change means a new collection. Create one with the new embedder and re-ingest; don't mix spaces in one collection.

```python
from telys.embedding import AlgentaBigramEmbedder, AlgentaMultigramEmbedder

old = AlgentaBigramEmbedder()
new = AlgentaMultigramEmbedder()
print(old.profile.space_id() == new.profile.space_id())   # False -> incompatible
print(new.profile.compatible_with(old.profile))           # False

# Re-ingest into a new collection built in the new space:
mem_new = mem.create_collection("notes_v2", dim=new.profile.dimension,
                                partition_by="scope", embedder=new)
```

On `open_collection`, Telys auto-attaches an embedder from the provider registry by matching `model_id` / `space_id`. If the registered embedder is in a different space, register the correct provider so it can attach the right one.

</details>

## Next steps

With widths lined up, the remaining "not finding it" cases are about scope, filters, and recall.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>No results / poor recall</strong></td><td>Empty hits, filters, embedder choice, recall tuning.</td><td><a href="https://docs.telys.ai/troubleshooting/search-and-recall.md">No results / recall</a></td></tr><tr><td><strong>Dimensions &#x26; space IDs</strong></td><td>How space identity is computed and why it matters.</td><td><a href="https://docs.telys.ai/embeddings/dimensions-and-space-id.md">Dimensions &amp; spaces</a></td></tr></tbody></table>

Next: [No results / poor recall](https://docs.telys.ai/troubleshooting/search-and-recall.md)
