# Troubleshoot an instance

What a common failure means, and what to do about it. During installation itself, the preflight
names its own stops - what is missing, why, and the command that fixes it - and
[INSTALL.md](../../INSTALL.md) explains them. This page covers an instance that is already set up.

For the MCP read server, see the troubleshooting section of
[Set up the MCP read server](set-up-the-mcp-server.md#troubleshooting).

## `tools/wikitool` ends with `STOP - this checkout is not set up yet` (exit 42)

The preflight has not run in this checkout yet, or not since the last update. Run it:

```bash
tools/preflight.sh
```

In PowerShell 7 on Windows, the call is
`pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1`. The `-ExecutionPolicy Bypass`
applies to that one process only and changes no setting.
[instructions/preflight.md](../../instructions/preflight.md) is the procedure, and its output says
what to install if anything is missing.

## The agent offers no skills (`wiki-ingest`, `wiki-query`, ...)

`.agents/skills/` and `.claude/skills/` are generated and not committed. Run:

```bash
tools/wikitool instructions sync
```

Then restart the agent session. A harness reads its skills only when the session starts.

## `doctor` reports `personalization: FAIL`

`USER.md` or `SOUL.md` is missing, or still carries the sentinel line from its template. A renamed
template does not count as a filled one. Ask the agent to run the personalization step of
[instructions/setup-instance.md](../../instructions/setup-instance.md). For a further clone of an
older instance, that is the only step to catch up on.

## `doctor` reports `environment: WARN`

`ENVIRONMENT.md` exists but still carries the template's sentinel line. Fill it in (the template is
`ENVIRONMENT.md.template`) and remove the line, or delete the file. It is optional, and `absent` is
a valid state.

## `new` stops with "No author configured"

Neither `$WIKI_AUTHOR` nor `git config user.name` is set. Run `git config user.name "<Name>"`, or
export `WIKI_AUTHOR` ([configuration](../reference/configuration.md)).

## `publish` ends with exit 42 (Mass-Update Gate)

Expected when ten or more files are counted, for example on the very first commit of a new instance
or after a lint pass. It is not an error. It asks that a human see the output: the complete file
list and the exact `--confirm <token>` line that publishes once you approve.
[instructions/gates.md](../../instructions/gates.md) has the details.

## `publish` ends with exit 42 (Publish-Remote Gate)

This checkout has a `.wikitool-remotes.json`, and the remote being pushed to is not listed in it.
Also not an error: the output names the push URL it would write to and the URLs that are allowed.
Unlike the Mass-Update Gate, there is **no token and no flag** here. If the target really is right,
you add its URL to the file yourself. An agent that edits the file to get past the refusal is
opening a gate on its own initiative, which it must never do.

## Setup or an update fails, and you want to report it

Ask the agent to follow [instructions/bug-report.md](../../instructions/bug-report.md), or call
`tools/bugreport` yourself. It works the same from Bash, Git Bash and PowerShell. It finds a
Python 3.8 or newer by itself, skipping the Store aliases `python3` points at on Windows. It needs
neither the preflight nor a working `wikitool`, and if it finds no Python, it says why.

The script writes a bundle to `reports/bugreport-<timestamp>/`, with a zip beside it.

- **What is removed:** secrets, and page titles from everything the script itself produces.
  `--titles` keeps the titles.
- **What may still be in it:** the session trace is included by default (`--no-trace` leaves it
  out). Like the chronology and the transcripts, it can contain page content and titles. The bundle
  also contains machine, user and path names.
- **Pseudonymising:** `--pseudonymise` replaces user, host, path, git and remote names with
  placeholders that keep their length, spaces, hyphens and path depth. The agent can then add more
  names - people, companies, customers, projects - with `--bundle … --candidates …`. That is a
  model's judgment, and it leaves a remainder: read the bundle before you share it. The mapping,
  the checklist and the candidates file contain the originals, and they sit beside the bundle,
  never in it.

Nothing is uploaded anywhere. You choose the channel.