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

# Troubleshooting

> Diagnose SelfTune installation, discovery, data, dashboard, and permission problems.

Start with the health check and preserve its exact output:

```bash theme={null}
npx selftune@latest doctor
```

| Symptom                   | Check                                                             | Next action                                                                  |
| ------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Agent cannot see SelfTune | Was the skill installed after the session started?                | Restart the agent session and ask it to inspect the installation             |
| Command is missing        | Is `npx` or Bun available?                                        | Run through `npx selftune@latest` and record the version                     |
| Skills are missing        | Are their directories visible to the current user and harness?    | Check discovery paths without moving or copying skills yet                   |
| Health says no data       | Has the skill been used in a supported recorded session?          | Use it naturally, end the session, then run `sync` and `status`              |
| Dashboard will not open   | Is another runtime using the port or an older service registered? | Run `doctor` and inspect service status before restarting                    |
| Permission error          | Which file, hook, history, or supervisor is blocked?              | Grant only the narrow permission required or choose a manual path            |
| Cloud or library fails    | Is the local workflow healthy first?                              | Keep local operation working, then check URL, identity, and token separately |

## Ask your agent to diagnose

```text theme={null}
Diagnose this SelfTune problem without changing the installation first. Run the
health check, record the SelfTune version and environment, identify the first
failing boundary, and propose the smallest reversible fix. Ask before changing
hooks, services, permissions, credentials, or data.
```

## Collect a useful report

Include the SelfTune version, operating system, agent harness, installation
path, exact command, exact error, expected result, and whether the problem also
occurs through the CLI. Remove tokens, prompts, transcripts, usernames, and
private filesystem paths before sharing a report.

Use a reproduce-minimize-diagnose loop. Begin read-only. Distinguish installation,
harness discovery, skill discovery, evidence ingestion, local runtime, and
remote connection boundaries. Do not reinstall or delete state as a first
step. Present the first supported root cause and a reversible fix, then verify
the original symptom.