Find the heading that matches what you see. Each section says why it happens and what to do.
First checks
Three commands answer most questions:
istok version # is Istok installed, and which version
istok project show # does this directory belong to a project
istok COMMAND --help # the exact flags your version acceptsBuilt-in help is the authoritative source for your installed binary. If a command behaves differently from these docs, trust --help and check istok version.
The agent does not see Istok tools
Why: the agent cannot start istok mcp. Most often the editor or desktop app has a different PATH from your terminal, so istok version works in the shell but not for the agent.
What to do:
- Check the MCP command in the agent’s configuration; it must run
istok mcp. - Make sure the
istokbinary is on thePATHof the agent’s process, or use its absolute path in the configuration. - Restart or reload the agent after changing its MCP configuration.
- Use the agent’s MCP status view to confirm the Istok server started.
Setup for each agent is in the Quick start.
The agent does not use Istok
Why: MCP only makes the tools available. When to use them comes from the agent’s instructions, and without them the agent may ignore Istok or use it inconsistently.
What to do: add the recommended instructions from the Quick start, and make sure the repository is registered (next section). For prompts that steer an agent back, see Working with your agent.
“Not registered” or Istok cannot find the project
Why: the directory is not inside a registered project, or you are not in the repository you think you are.
What to do: check where you are and what is registered:
pwd
istok project listIf the repository is missing, ask your agent to “register this project in Istok”, or run istok init in the repository. Then confirm with istok project show.
I moved or renamed the repository folder
Why: a project is bound to a path. After a move, the new path is not registered.
What to do: rebind the existing project instead of registering a new one, so tasks and history stay attached:
cd ~/projects/acme-api
istok project rebind acme-apiThe agent works in the wrong project
Why: each istok mcp process uses the project of the directory the agent was started in, and keeps it until it exits. With nested projects, the closest one wins.
What to do: start the agent from the right directory, and check with istok project show from there. Do not register another project just to make a session work.
The CLI, the agent, and the UI show different data
Why: they are using different databases. Each process reads the database given by --database or ISTOK_DATABASE, falling back to the default location. The UI service does not see your shell’s environment.
What to do: use the same database everywhere. If you use a custom one, pass it to the agent’s MCP command and reinstall the UI service with it:
istok ui service install --database /path/to/istok.dbA task is stuck in progress
Why: its run is probably stale. The agent session ended without finishing the run, heartbeats stopped, and the lease has not expired yet or nobody has claimed the task since.
What to do: check the Stale filter in the runs feed of the web UI, or list the task’s runs:
istok run list --task 12Once the lease expires, the next claim closes the stale run as abandoned automatically. To release it now, abandon the run from the web UI or with istok run abandon. See Tasks and runs.
A task cannot be claimed
Why: the task is not ready. It has an active blocking dependency, another live run owns it, or its state changed since you last looked.
What to do:
istok task show 12
istok task ready
istok run list --task 12Resolve blockers first. If a live run owns the task, wait for it or, if nobody is working on it, abandon it as described above.
A claim fails because of the context budget
Why: the context that must be delivered, always records and records requested by ID, does not fit into the context budget. Istok fails the claim rather than silently dropping your rules. The error names the records involved.
What to do: find the cause, fix it, and check before claiming again:
istok context doctor
istok context update RECORD_ID --expected-revision REVISION --delivery ranked
istok context preview 12Shorten or split oversized records, or move nonessential always records to ranked.
A claim fails while preparing code context
Why: a claim refreshes the code index and retrieves code before it creates the run. If no usable index can be prepared, it fails instead of starting with stale code.
What to do:
istok index status
istok index rebuild
istok task claim 12Fix retrieval rather than bypassing it. --without-retrieval with an --override-reason exists for exceptional cases.
Search results look wrong or out of date
Why: rare, because search checks freshness and refreshes the index automatically. If no usable index can be prepared, search fails rather than returning stale results.
What to do: inspect and, if needed, repair:
istok index status
istok index rebuildIf the rebuild also fails, the status output is the starting point for finding which files or index state cause the problem.
The graph is degraded
Why: some files could not contribute complete structural information. Search keeps working; the graph is incomplete. The graph covers Go, TypeScript, and JavaScript only.
What to do: check istok index status. If you need the graph and the problem persists, run istok index rebuild and check again.
A run command rejects the lease
Why: exec, validate, heartbeat, and finish need the run’s current lease. It changes on recovery, so an older lease no longer works.
What to do: get the current state with istok run show RUN_ID and use the current lease. If you lost the lease and are the same actor, recover the run to get a new one:
istok run recover RUN_ID --reason "Lost local lease token"If the old lease is still active, add --force. Recovery only works for the actor that owns the run.
An operation fails with a stale revision
Why: tasks, runs, context records, and knowledge items use revisions. If something changed the object after you read it, an operation with the old --expected-revision is rejected instead of overwriting the newer state.
What to do: read the object again (istok task show 12, istok run show RUN_ID, istok context show RECORD_ID) and retry with the latest revision. Retrying with the old one will keep failing.
Validation fails
Why: the check did not pass. That is recorded, not lost.
What to do: inspect the output with istok run show RUN_ID or in the web UI, fix the problem, and validate again in the same run. There is no need for a new task. See Validation.
A run cannot be finished
Why: finishing as succeeded needs the current lease, the current run revision, no managed execution still running, and a passed validation.
What to do: check istok run show RUN_ID, validate if nothing has passed yet, then finish with the current values. If no automated check applies, finish explicitly with --allow-unvalidated and an --override-reason. See istok run.
I want to drop an attempt and start over
Why: an approach did not work, but the task is still valid.
What to do: abandon the run. The task stays open and the run stays in its history:
istok run abandon RUN_ID \
--expected-revision REVISION \
--reason "Restarting with a different approach"Agents can do this only with the supervisor or admin MCP profile.
The web UI does not open
Why: usually the port is taken, often by another istok ui or by the UI service, which already serves the UI.
What to do: open http://127.0.0.1:7700 to check whether the UI is already running. Otherwise start on another port:
istok ui --port 7800If the page says the web UI is not built, the binary was built from source without the frontend. Install an official release, or build with make install, which builds the frontend first.
The UI service stops after I log out
Why: on Linux, systemd stops user services when your last session ends.
What to do: enable lingering for your user:
loginctl enable-lingerOn macOS the launchd agent belongs to your login session by design: it stops when you log out and starts again when you log in.
Reporting a problem
Collect a small diagnostic set:
istok version
istok project show
istok index status
istok task show TASK_ID
istok run show RUN_IDFor MCP problems, include the agent’s MCP configuration and whether the agent can start the Istok server. Remove secrets and private project content before sharing anything publicly.