> 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 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). | Use `upsert`/`upsert_texts`, or a fresh id. | | `ValueError` | `telys` | A search vector length ≠ `dim` (`len(vector) != dim`). | Match the collection `dim`. | | `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"}]) col.add_texts(["b"], ids=["dup"], metadata=[{"scope": "demo"}]) # KeyError: id already exists col.upsert_texts(["b"], ids=["dup"], metadata=[{"scope": "demo"}]) # OK — replaces ``` ### Dimension and shape mismatches ```python col = ame.create_collection("v", dim=384, partition_by="scope") col.search([0.0] * 128) # ValueError: vector length 128 != dim 384 ``` 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
Environment & exit codesCLI environment variables and codes./pages/pnaayefJXBBFBA2KHufD
Install & runtime issuesFix RuntimeNotInstalled and import errors./pages/sTZH257W259P14bHy2EA
Signature verification failuresResolve VerificationError./pages/0eykLEyLKnupmpNlVgH9
Embedding dimension mismatchesResolve ValueError on length, AssertionError on shape./pages/cLf0cG2Rm2TZeyApGR9I
--- # 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/reference/exceptions-and-errors.md?ask=&goal= ``` `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.