> 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

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 inserts fail their shape check. `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="/pages/oKbcrBs3CQX8o02wjPZN">/pages/oKbcrBs3CQX8o02wjPZN</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="/pages/MIVK3hfr15xmitNeowAz">/pages/MIVK3hfr15xmitNeowAz</a></td></tr></tbody></table>

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/troubleshooting/dimension-mismatches.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.