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

# Troubleshooting

> Check missing endpoints and sessions, repair hooks, and diagnose policy enforcement.

Run these commands on the affected endpoint:

```bash theme={"system"}
kontext --version
kontext doctor
kontext whoami
```

`kontext doctor` checks the configuration, the API key, the daemon, the export backlog and the hooks for each agent.

## The endpoint is missing from Home

Check that `kontext whoami` names the workspace you have open. The dashboard shows an endpoint only in its connected workspace.

If doctor prints `config: not configured`, the endpoint needs setup. Run `kontext setup` on a self-serve endpoint. For an MDM-managed endpoint, check the package deployment in your MDM.

Home shows removed endpoints again at their next check-in. Endpoints with a CLI older than 1.5.0 check in without reporting agents. Home counts these endpoints in a note below the endpoints table.

## Sessions are missing for an endpoint

1. Widen the time range in [Explore](/explore/overview). The dashboard shows activity after a short delay.
2. Check the `export` line in doctor. `up to date (0 pending)` means the endpoint sent every record. A growing pending count means the endpoint cannot reach your workspace.
3. Open the endpoint on [Home](/home/overview) and check the agent's hook status. **Missing** means Kontext cannot see that agent's activity.
4. For Codex, open `/hooks` and trust the Kontext hooks. Doctor cannot check hook trust.
5. Check whether Claude Cowork runs the session in Anthropic's cloud. Kontext cannot observe those sessions yet.

Then run one read-only tool call and look for it in Explore.

## The daemon is stale or not running

If the daemon runs an older binary than the endpoint's installed version, doctor prints `run 'kontext doctor --fix' to restart it`. Restart the daemon:

```bash theme={"system"}
kontext doctor --fix
```

`--fix` restarts the stale daemon and waits for it to start. For other problems, doctor prints `no automatic fixes are available for the reported issues`. You must fix those issues manually.

Doctor can report `daemon: not running (it starts with your next Claude Code session)` on an idle endpoint. You do not need to fix this. If the daemon repeatedly fails to start, read its log:

```text theme={"system"}
~/Library/Logs/Kontext/managed-observe.log
```

On an MDM-managed endpoint, follow doctor's restart instructions by redeploying the package through your MDM.

## Hooks are missing

On a self-serve endpoint, rerun `kontext setup` to rewrite the hooks. Kontext preserves unrelated hooks and settings. On an MDM-managed endpoint, redeploy the package. Home shows **Installed** in the endpoint drawer after its next check-in.

Doctor also checks the Codex hooks feature. `disabled by user override` means the user's `config.toml` disables hooks, including system hooks. [What Kontext installs](/deploy/what-kontext-installs) lists every file doctor checks.

## Kontext hooks Codex twice

If you deployed Kontext manually before deploying the MDM package, doctor prints `Codex hooks: another Kontext install also hooks Codex` with the extra hooks' path. Run `kontext setup --uninstall` on that endpoint. Kontext removes the self-serve setup and preserves the MDM-managed package.

## A policy does not block

Find the policy under **Authorization → Policies**. The **Observing** list shows what policies would block without blocking tool calls. Move the policy to the **Enforced** list to block tool calls. See [rollout](/policies/rollout).

If tool calls still run with the policy in **Enforced**, check the badge on Policies. The mode warning badge means the MDM package fixes the endpoint's mode. Set the package mode to `remote` to let the dashboard control it. The catching-up badge means the newest reported decision used a different mode from the workspace setting. Check a new decision from each rollout endpoint to confirm it applied the change.

## The API key stopped working

Revoking an API key immediately stops endpoints using it from reporting. A personal API key from **Get started** connects one endpoint. You must use it within 24 hours. If setup rejects the API key on a self-serve endpoint, get a new command from **Get started** or create an API key under **Settings → API Keys**. Rerun `kontext setup`. For MDM-managed endpoints, get a new key from your Kontext contact and update it in your MDM.

If doctor cannot read the API key, unlock your login keychain or rerun `kontext setup`.

## Share diagnostics

When you contact support, include `kontext --version` and `kontext doctor` output. Name the affected agent and approximate time. Include any error text. Exclude API keys and unredacted credentials.