> 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/reference/exceptions-and-errors.md).

# Exceptions & errors

Reference for the exceptions Telys raises across the SDK, server, and verify APIs, plus what each CLI exit code means.

What Telys raises, where it comes from, and how to respond. Most failures are one of a small set of exceptions; the CLI maps them onto three exit codes.

## SDK exceptions

| Exception             | Module                      | Raised when                                                                                                                                                                                                                                                    | Do this                                                                                |
| --------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `RuntimeNotInstalled` | `telys.runtime`             | `load_runtime()` cannot import the selected runtime.                                                                                                                                                                                                           | `telys runtime install`, then `telys runtime verify`.                                  |
| `ImportError`         | `telys` / `telys.embedding` | Importing a runtime-only class (`HeuristicTuner`, `AlgentaPooledEmbedder`) without the runtime, or instantiating an Algenta embedder without the native kernel.                                                                                                | Install/verify the runtime; set `$TELYS_KERNEL` if the kernel is elsewhere.            |
| `RuntimeError`        | `telys`                     | A `*_texts` call (`add_texts`, `search_text`, …) runs with no embedder attached.                                                                                                                                                                               | Attach an embedder on `create_collection`/`open_collection`.                           |
| `KeyError`            | `telys`                     | `add`/`add_texts` receives an id that already exists (they insert **new** rows only). Message: `ids already exist: [...]` (first batch) or `ids already exist (use upsert): [...]` (after the base seals).                                                     | Use `upsert`/`upsert_texts`, or a fresh id.                                            |
| `ValueError`          | `telys`                     | A search vector length ≠ `dim`; an ingest batch fails the `(n, dim)` shape check; an embedder's dimension ≠ `dim` at `create_collection`; or `update_texts` targets ids that don't exist (`update_texts: ids do not exist (use upsert_texts to insert): ...`). | Match the collection `dim`; update only live ids — insert with `upsert_texts` instead. |
| `AssertionError`      | `telys.embedding`           | A `CallableEmbedder` `fn` returns the wrong shape (`ndim != 2` or `shape[1] != dimension`).                                                                                                                                                                    | Return an `(N, dimension)` float32 array from your `fn`.                               |
| `VerificationError`   | `telys.verify`              | A manifest signature, artifact hash, or license fails strict offline verification.                                                                                                                                                                             | Re-install from a trusted source; check the issuer/audience/expiry.                    |
| `RemoteError`         | `telys.client`              | The server returns an error over the wire (bad request, auth failure, unknown collection).                                                                                                                                                                     | Read the message; check the address, token, and collection name.                       |

### Ingest id conflicts

```python
col.add_texts(["a"], ids=["dup"], metadata=[{"scope": "demo"}])     # first batch — seals the base
col.add_texts(["b"], ids=["dup"], metadata=[{"scope": "demo"}])     # KeyError: "ids already exist (use upsert): ['dup']"
col.upsert_texts(["b"], ids=["dup"], metadata=[{"scope": "demo"}])  # OK — replaces
col.update_texts(["c"], ids=["nope"], metadata=[{"scope": "demo"}]) # ValueError: update_texts: ids do not exist (use upsert_texts to insert): nope
```

`update_texts` is strict: every id must already be live — an unknown or deleted id raises instead of silently inserting a stray record. Mixed new+existing batches belong in `upsert_texts`.

### Dimension and shape mismatches

```python
from telys import Telys

ame = Telys("./memory")
col = ame.create_collection("v", dim=384, partition_by="scope")
col.search([0.0] * 128)   # ValueError: query vector must have length 384; got (128,)
```

A `CallableEmbedder` whose `fn` returns the wrong shape raises `AssertionError`, not `ValueError`:

```python
import numpy as np
from telys.embedding import CallableEmbedder, EmbeddingProfile

prof = EmbeddingProfile("me", "toy", "v1", dimension=8)
bad = CallableEmbedder(lambda xs: np.zeros((len(xs), 4), dtype="float32"), prof)  # returns (N, 4), not (N, 8)
bad.embed_documents(["hi"])   # AssertionError: shape[1] 4 != dimension 8
```

### Runtime-only imports

```python
from telys import HeuristicTuner              # ImportError without the runtime
from telys.embedding import AlgentaPooledEmbedder  # ImportError without the runtime
from telys.embedding import AlgentaBigramEmbedder  # import OK — resolves without the kernel
AlgentaBigramEmbedder()                            # ImportError without the native kernel
```

### Verification failures

```python
import time
from telys.verify import verify_license, VerificationError

try:
    claims = verify_license(token, now=int(time.time()))   # strict offline RS256
except VerificationError as e:
    print("license rejected:", e)
```

`verify_license` pins `RS256`, rejects `crit`, and checks issuer, audience, `ver == 2`, and expiry (with grace) before returning the `products.telys` tier and features.

### Remote errors

```python
from telys.client import connect, RemoteError

try:
    with connect("tcp://localhost:8899", token="$TELYS_ACCESS_TOKEN") as c:
        c.open_collection("missing")
except RemoteError as e:
    print("server said:", e)
```

## CLI exit codes

Every `telys` command returns one of three codes.

| Code | Meaning                      | Examples                                                                                                                                   |
| ---- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `0`  | Success / ready.             | Any command that completes; bare `telys` (prints help); `telys runtime status` when the runtime is ready.                                  |
| `1`  | Error / not ready.           | `telys runtime status` when the runtime is not installed; a fatal error during a command.                                                  |
| `2`  | Usage error / unimplemented. | `telys serve` without `--socket` or without both `--host` and `--port`; `telys runtime update` (a stub that prints "not implemented yet"). |

```bash
telys runtime status; echo "exit=$?"   # exit=0 ready, exit=1 not
telys runtime update;  echo "exit=$?"  # prints "not implemented yet", exit=2
telys serve --path ./memory; echo "exit=$?"  # exit=2 (no socket/host+port)
```

{% hint style="info" %}
The runtime signature is verified via `telys runtime verify` (and the `telys.verify` API), not a standalone `telys verify` command — there is no such command.
{% endhint %}

## See also

<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>Environment &#x26; exit codes</strong></td><td>CLI environment variables and codes.</td><td><a href="https://docs.telys.ai/cli/environment-and-exit-codes.md">Environment &amp; exit codes</a></td></tr><tr><td><strong>Install &#x26; runtime issues</strong></td><td>Fix RuntimeNotInstalled and import errors.</td><td><a href="https://docs.telys.ai/troubleshooting/install-and-runtime.md">Install &amp; runtime</a></td></tr><tr><td><strong>Signature verification failures</strong></td><td>Resolve VerificationError.</td><td><a href="https://docs.telys.ai/troubleshooting/signature-verification.md">Signature verification</a></td></tr><tr><td><strong>Embedding dimension mismatches</strong></td><td>Resolve ValueError on length, AssertionError on shape.</td><td><a href="https://docs.telys.ai/troubleshooting/dimension-mismatches.md">Dimension mismatches</a></td></tr></tbody></table>
