> 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

Start here when something breaks — a 60-second triage with telys runtime status, telys runtime verify, and telys version, then jump to the page for your problem.

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.15 (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](https://docs.telys.ai/troubleshooting/install-and-runtime.md)           |
| `telys version` prints, `runtime status` exits `1`      | SDK is fine; the signed runtime is missing.                      | [Install & runtime issues](https://docs.telys.ai/troubleshooting/install-and-runtime.md)           |
| `RuntimeNotInstalled` from Python                       | No runtime for any collection op.                                | [Install & runtime issues](https://docs.telys.ai/troubleshooting/install-and-runtime.md)           |
| `runtime verify` reports a signature or license failure | Runtime present but not trusted.                                 | [Signature verification failures](https://docs.telys.ai/troubleshooting/signature-verification.md) |
| Login or license errors                                 | Device-code sign-in, or an expired / wrong-plan license.         | [License & login issues](https://docs.telys.ai/troubleshooting/license-and-login.md)               |
| Search returns nothing, or bad matches                  | Filter, partition, or embedder mismatch, or recall needs tuning. | [No results / poor recall](https://docs.telys.ai/troubleshooting/search-and-recall.md)             |
| `ValueError` about dimension / length                   | Vector width doesn't match the collection or embedder.           | [Embedding dimension mismatches](https://docs.telys.ai/troubleshooting/dimension-mismatches.md)    |
| Your editor doesn't show Telys tools                    | MCP server not spawned or env not delivered.                     | [MCP client won't connect](https://docs.telys.ai/troubleshooting/mcp-client.md)                    |
| macOS / Linux / Windows-specific error                  | Gatekeeper, arch, or WSL2.                                       | [Platform-specific issues](https://docs.telys.ai/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 --license ./license.jwt
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="https://docs.telys.ai/troubleshooting/install-and-runtime.md">Install &amp; runtime</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="https://docs.telys.ai/troubleshooting/license-and-login.md">License &amp; login</a></td></tr><tr><td><strong>Signature verification failures</strong></td><td>Manifest/artifact hash mismatch, bad license claims.</td><td><a href="https://docs.telys.ai/troubleshooting/signature-verification.md">Signature verification</a></td></tr><tr><td><strong>No results / poor recall</strong></td><td>Empty hits, wrong embedder, recall tuning.</td><td><a href="https://docs.telys.ai/troubleshooting/search-and-recall.md">No results / recall</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="https://docs.telys.ai/troubleshooting/dimension-mismatches.md">Dimension mismatches</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="https://docs.telys.ai/troubleshooting/mcp-client.md">MCP client</a></td></tr><tr><td><strong>Platform-specific issues</strong></td><td>Gatekeeper, Linux arm64, Windows via WSL2.</td><td><a href="https://docs.telys.ai/troubleshooting/platform-specific.md">Platform-specific</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="https://docs.telys.ai/reference/exceptions-and-errors.md">Exceptions &amp; errors</a></td></tr></tbody></table>
