> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slaunt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Slaunt connections and tool errors

> Causes and fixes for Slaunt auth, session, lifecycle, hook, Gateway and quota problems.

Find the symptom or error text below. The full code list is in [Errors](https://docs.slaunt.ai/protocol/errors.md).

## Connection

| Symptom | Cause | Fix |
| - | - | - |
| `401` `invalid_token` | Token missing or expired. Tokens are per client. | Claude Code: `/mcp` → `slaunt` → Authenticate. Codex: restart to re-login. |
| `400` session header required | Client isn't keeping `Mcp-Session-Id` | Persist it from the `initialize` response |
| `404` Unknown MCP session | Session expired, or reused with another token or client | Re-initialize. If it happens every time, two clients are sharing a session. |
| Installer: entry already exists | A previous Slaunt config is present | Re-run with `--overwrite-config` |

## Lifecycle and hooks

| Symptom | Cause | Fix |
| - | - | - |
| `run_begin is invalid while thread state is RUNNING` | A run is already active, usually started by a hook | With hooks, don't call `run_begin` from the model. Otherwise `run_end` first. |
| `thread_begin is invalid while thread state is RUNNING` | Rotating threads mid-run | `run_end`, then `thread_begin` with `new_thread: true` |
| `run_step is invalid while thread state is IDLE` | No active run | `run_begin` first |
| Tool calls denied: `runtime_stopped` | Agent was stopped in Quaero or KillBar | Intended. A new prompt starts a fresh run. |
| Tool calls denied: `run_not_active` | The `UserPromptSubmit` hook didn't start a run | Restart the client so hooks and MCP come up together |
| Codex chats merge or split oddly | Hook and tool calls don't share `threadId` | See [Codex thread routing](https://docs.slaunt.ai/clients/codex.md#thread-routing) |

## Tools and quotas

| Symptom | Cause | Fix |
| - | - | - |
| A documented tool isn't listed | It's [conditional](https://docs.slaunt.ai/tools/overview.md) | Check the conditions |
| Provider tools missing | Gateway discovery failed or nothing connected | Read `_meta["ai.slaunt/gateway-discovery"]` in `tools/list` |
| `Agent quota has been hit` | Concurrent agent limit | End idle sessions in Quaero or upgrade |
| `... quota has been hit for the ... plan` | Monthly quota used | Wait for the reset (1st, UTC) or upgrade |
| Context summary cut off | 20-word limit | Shorten it |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.