istok

Troubleshooting

Diagnose common Istok project, MCP, task, run, validation, and repository retrieval problems.

Most Istok problems can be diagnosed by checking three things first: the current project, the command arguments, and the state Istok has already recorded.

Start with these checks

Confirm that Istok is available:

istok version

Confirm that the current repository resolves to an Istok project:

istok project show

If a command rejects an argument or flag, inspect its built-in help:

istok COMMAND --help

For example:

istok task claim --help
istok run validate --help

Istok cannot find the current project

If:

istok project show

does not resolve the repository, first check that you are working in the repository you expect.

List registered projects:

istok project list

The repository has not been initialized

If the repository is not registered with Istok, initialize it from the repository:

istok init

Then verify:

istok project show

The repository was moved

If the project already exists but the repository has moved to another path, keep the existing Istok project and rebind it instead of initializing a second project.

From the new repository location:

istok project rebind PROJECT

Or provide the path explicitly:

istok project rebind PROJECT /path/to/repository

The existing tasks, context, runs, and other project state remain associated with the project.

The agent cannot see Istok

MCP configuration must start:

istok mcp

If the agent reports that Istok tools are unavailable:

  1. Confirm that istok is available in the environment used by the coding agent.
  2. Check the agent’s configured MCP command.
  3. Restart or reload the agent after changing its MCP configuration.
  4. Use the agent’s MCP status view to confirm that the Istok server started successfully.

A common issue is that an editor or desktop application has a different PATH from your interactive shell.

If:

istok version

works in your terminal but the MCP client cannot start istok, configure the client so the Istok executable is available to its process environment.

The agent sees the wrong project

An istok mcp process operates relative to the repository it is started for.

Check the working directory of the agent session and verify the project from the same repository:

istok project show

Do not initialize another project just to make an existing MCP session work.

If the repository itself has moved, use project rebind.

CLI and MCP show different project state

Make sure the CLI and MCP server are using the same Istok database.

Check whether you have set:

ISTOK_DATABASE

and whether either process uses an explicit:

--database

option.

For example, these refer to different Istok state if the paths differ:

ISTOK_DATABASE="$HOME/a.db" istok task list

istok mcp --database "$HOME/b.db"

Use the same database configuration when CLI and MCP should see the same projects and tasks.

A task cannot be claimed

Start by inspecting the task:

istok task show 12

Then check ready work:

istok task ready

A task may not be ready because:

  • it has an active blocking dependency;
  • another live run is already working on it;
  • its state has changed since you last inspected it.

Resolve blockers before claiming the task.

If another active run owns the task, inspect its state:

istok run list --task 12

and:

istok run show RUN_ID

An active run with a valid lease prevents another normal claim.

If the previous run’s lease has expired, the task can become ready again and a later claim can start the next attempt.

A run lease is rejected

Run operations such as exec, validate, and heartbeat require the current lease:

istok run show RUN_ID

Inspect the run and use the lease returned by its current state.

For example:

istok run validate RUN_ID \
  --lease LEASE \
  -- pnpm test

Do not reuse an older lease after it has been replaced.

You lost the lease token

If you are continuing the same run as the same actor, recover it:

istok run recover RUN_ID \
  --reason "Lost local lease token"

Recovery returns a new lease. Use that lease for subsequent operations.

If the existing lease is still active, forced recovery requires an explicit reason:

istok run recover RUN_ID \
  --force \
  --reason "Replacing stale local session"

A revision is stale

Tasks, runs, and context records use revisions to protect state-changing operations from stale writes.

If an operation rejects:

--expected-revision

read the object again.

For a task:

istok task show 12

For a run:

istok run show RUN_ID

For context:

istok context show RECORD_ID

Use the latest returned revision and retry the operation.

Do not keep retrying with the old revision.

Validation fails

A failed validation means the recorded check did not succeed.

Inspect the run:

istok run show RUN_ID

Fix the problem and run validation again:

istok run validate RUN_ID \
  --lease LEASE \
  -- COMMAND

For example:

istok run validate RUN_ID \
  --lease LEASE \
  -- go test ./...

or:

istok run validate RUN_ID \
  --lease LEASE \
  -- pnpm test

Failed validation remains useful execution history. You do not need to create a new task simply because a check failed.

A run cannot be finished

Inspect it first:

istok run show RUN_ID

A normal successful finish requires:

  • the current lease;
  • the current run revision;
  • no managed execution still running;
  • successful validation evidence.

If validation has not passed, validate the implementation before finishing the run.

Then use the current state:

istok run finish RUN_ID \
  --lease LEASE \
  --expected-revision REVISION \
  --status succeeded \
  --summary "Implementation complete and validated."

If the lease or revision changed, inspect the run again before retrying.

A previous attempt should not continue

If a run represents an attempt that should be stopped while keeping the task open, it can be abandoned:

istok run abandon RUN_ID \
  --expected-revision REVISION \
  --reason "Restarting with a different approach"

The task remains available for another attempt.

In agent workflows, explicit run abandonment requires the appropriate MCP access.

Search results look out of date

Repository search checks index freshness automatically:

istok search "authentication"

You normally do not need to update the index manually before searching.

If retrieval appears incorrect, inspect its state:

istok index status

If the index needs repair, rebuild it:

istok index rebuild

Then retry the search.

Task claim fails while preparing repository context

Task claim prepares repository retrieval before creating the run.

If retrieval cannot be prepared, the claim can fail without creating a new run.

Inspect the index:

istok index status

Then try repairing it:

istok index rebuild

After the rebuild succeeds, retry:

istok task claim 12

You normally should fix repository retrieval rather than bypass it.

The graph is degraded

The lexical repository index and structural code graph are related but do not always have the same health.

Check:

istok index status

A degraded state can mean that repository search remains usable while structural information for some files is incomplete.

You can still try:

istok search "authentication"

If you need the graph and the problem persists, rebuild the index:

istok index rebuild

and inspect the status again.

Search or graph cannot build a usable index

If:

istok search ...

or a graph command fails because no usable repository index can be prepared, Istok does not silently fall back to stale retrieval results.

Inspect:

istok index status

and rebuild:

istok index rebuild

If the rebuild also fails, the status output should be the starting point for diagnosing which repository files or index state caused the problem.

A command behaves differently from the documentation

Inspect the command shipped with your installed Istok version:

istok COMMAND --help

For example:

istok run exec --help

and check your version:

istok version

Built-in command help is the authoritative source for the exact flags and arguments accepted by the installed binary.

Still stuck?

Collect the smallest useful diagnostic set before investigating further:

istok version
istok project show
istok index status

For task or run problems, also include:

istok task show TASK_ID
istok run show RUN_ID

When reporting an MCP problem, include the MCP configuration used by the coding agent and whether the agent can start the Istok server.

Avoid including secrets or private project content in diagnostic output that you share publicly.

Continue with the FAQ for answers to common questions about how Istok is intended to be used.