> 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/overview.md).

# Overview

Most Telys problems are one of a few things: the **signed runtime isn't installed or verified**, your **license or login isn't in place**, an **embedder dimension doesn't match a collection**, or an **MCP client can't spawn the server**. Run the triage below, then follow the link for your symptom.

{% hint style="success" %}
Run the three triage commands first. In order, they tell you whether the SDK is installed, whether the runtime is present and trusted, and whether it's ready for collection operations.
{% endhint %}

## 60-second triage

Each command isolates a different layer, from the outside in.

```bash
telys version          # SDK present? prints: telys 0.1.0b2 (format v1)
telys runtime status   # runtime installed & ready? exit 0 = ready, 1 = not
telys runtime verify   # runtime signature + license trusted?
```

Match the output against this table.

| What you see                                            | What it means                                                    | Go to                                                                         |
| ------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `telys: command not found`                              | The SDK isn't installed (or not on `PATH`).                      | [Install & runtime issues](/troubleshooting/install-and-runtime.md)           |
| `telys version` prints, `runtime status` exits `1`      | SDK is fine; the signed runtime is missing.                      | [Install & runtime issues](/troubleshooting/install-and-runtime.md)           |
| `RuntimeNotInstalled` from Python                       | No runtime for any collection op.                                | [Install & runtime issues](/troubleshooting/install-and-runtime.md)           |
| `runtime verify` reports a signature or license failure | Runtime present but not trusted.                                 | [Signature verification failures](/troubleshooting/signature-verification.md) |
| Login or license errors                                 | Device-code sign-in, or an expired / wrong-plan license.         | [License & login issues](/troubleshooting/license-and-login.md)               |
| Search returns nothing, or bad matches                  | Filter, partition, or embedder mismatch, or recall needs tuning. | [No results / poor recall](/troubleshooting/search-and-recall.md)             |
| `ValueError` about dimension / length                   | Vector width doesn't match the collection or embedder.           | [Embedding dimension mismatches](/troubleshooting/dimension-mismatches.md)    |
| Your editor doesn't show Telys tools                    | MCP server not spawned or env not delivered.                     | [MCP client won't connect](/troubleshooting/mcp-client.md)                    |
| macOS / Linux / Windows-specific error                  | Gatekeeper, arch, or WSL2.                                       | [Platform-specific issues](/troubleshooting/platform-specific.md)             |

{% hint style="info" %}
`telys version` never needs the runtime and prints in a fresh install. `telys runtime status` and `telys runtime verify` need the runtime present; a non-zero exit is a signal, not a crash.
{% endhint %}

## The two commands that fix most of it

If triage points at the runtime, these restore a trusted, ready state.

```bash
telys login              # signs in (free telys_developer) and installs the runtime
telys runtime verify     # confirms the signature + license before you rely on it
```

For an air-gapped or CI host with a signed bundle on disk, install it offline instead.

```bash
telys runtime install --file ./telys-runtime-macos-arm64.bundle
telys runtime status
```

## Next steps

Pick the page for your symptom. Each is a full guide with a copy-paste fix per error.

<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>Install &#x26; runtime issues</strong></td><td>RuntimeNotInstalled, runtime download, kernel not found.</td><td><a href="/pages/sTZH257W259P14bHy2EA">/pages/sTZH257W259P14bHy2EA</a></td></tr><tr><td><strong>License &#x26; login issues</strong></td><td>Login fails, expired/invalid license, wrong plan, headless.</td><td><a href="/pages/f5D2AxbBcG8bokGMGJNZ">/pages/f5D2AxbBcG8bokGMGJNZ</a></td></tr><tr><td><strong>Signature verification failures</strong></td><td>Manifest/artifact hash mismatch, bad license claims.</td><td><a href="/pages/0eykLEyLKnupmpNlVgH9">/pages/0eykLEyLKnupmpNlVgH9</a></td></tr><tr><td><strong>No results / poor recall</strong></td><td>Empty hits, wrong embedder, recall tuning.</td><td><a href="/pages/oKbcrBs3CQX8o02wjPZN">/pages/oKbcrBs3CQX8o02wjPZN</a></td></tr></tbody></table>

<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>Dimension mismatches</strong></td><td>Vector width vs the collection or embedder profile.</td><td><a href="/pages/cLf0cG2Rm2TZeyApGR9I">/pages/cLf0cG2Rm2TZeyApGR9I</a></td></tr><tr><td><strong>MCP client won't connect</strong></td><td>Server not detected, env block, missing tools.</td><td><a href="/pages/oK1vZXEvrJ6ET1JcSX8G">/pages/oK1vZXEvrJ6ET1JcSX8G</a></td></tr><tr><td><strong>Platform-specific issues</strong></td><td>Gatekeeper, Linux arm64, Windows via WSL2.</td><td><a href="/pages/1rwJMQiVqqVsvqlbVWbC">/pages/1rwJMQiVqqVsvqlbVWbC</a></td></tr><tr><td><strong>Exceptions &#x26; error codes</strong></td><td>The canonical list of exception types Telys raises.</td><td><a href="/pages/6XF5eSw2bmrtE5ICxHTM">/pages/6XF5eSw2bmrtE5ICxHTM</a></td></tr></tbody></table>


---

# 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/overview.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.