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

# Troubleshooting

> Check installation, capture, background work, tasks, and the Viewer.

# Troubleshooting

Start with:

```bash theme={null}
termyte doctor
termyte viewer
```

## No events appear

1. Run `termyte init` again.
2. Restart the selected coding agent.
3. Complete a task that uses at least one tool.
4. Confirm the agent process sees the same `TERMYTE_HOME` and `TERMYTE_DB` values as your terminal.
5. Inspect sessions and diagnostics in the Viewer.

For OpenCode, confirm that both `~/.config/opencode/plugins/termyte.js` and its entry in `opencode.json` exist. `doctor` does not currently check OpenCode.

## Hooks are partial or missing

`termyte doctor` lists missing Claude Code and Codex hook events. Re-run setup after upgrading Termyte or moving Node:

```bash theme={null}
npm install -g termyte@latest
termyte init
```

## Background work is stuck

Open the Viewer diagnostics. Check pending, leased, failed, and dead jobs. The worker uses leases and retries; dead jobs need operator attention.

If automatic worker startup was disabled with `TERMYTE_AUTO_WORKER=0`, run the installed `termyte-worker` binary yourself.

## Task update reports a version conflict

Another process changed the task first. Run `termyte task show --task <task-id>`, read the new version, and retry only after reviewing the newer state.

## A step cannot be verified

Use the current task version and include `--confirm yes`. The task service will not accept agent-authored verification or missing passing evidence.

## Resume shows unexpected drift

Check the current branch, commit, modified paths, deleted paths, untracked files, and merge conflicts. Create a new checkpoint only after deciding that the current checkout is the state you want to preserve.

## The first retrieval is slow

The local embedding model may be downloading and loading. Keyword retrieval remains available when embeddings cannot initialize.

## Expected context is missing

Termyte may reject stored context when a referenced file changed, disappeared, or points outside the current workspace. Check the current Git status and inspect the context packet in the Viewer. If Git or the workspace cannot be checked, the result is marked unverifiable instead of current.

## Session processing failed

Open Viewer diagnostics and look for a failed or dead `consolidate_session` job. The worker retries temporary failures. A dead job remains visible for operator review.

## Resetting data

Termyte has no public delete command. Stop agents, the Viewer, MCP clients, and workers before manually removing the configured database and its adjacent WAL files. This permanently removes the local corpus.