# 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). ## Contents - [`tools/wikitool` ends with `STOP - this checkout is not set up yet` (exit 42)](#toolswikitool-ends-with-stop---this-checkout-is-not-set-up-yet-exit-42) - [The agent offers no skills (`wiki-ingest`, `wiki-query`, ...)](#the-agent-offers-no-skills-wiki-ingest-wiki-query) - [`doctor` reports `personalization: FAIL`](#doctor-reports-personalization-fail) - [`doctor` reports `environment: WARN`](#doctor-reports-environment-warn) - [`doctor` reports `telemetry: WARN`](#doctor-reports-telemetry-warn) - [`new` stops with "No author configured"](#new-stops-with-no-author-configured) - [`publish` ends with exit 42 (Mass-Update Gate)](#publish-ends-with-exit-42-mass-update-gate) - [`publish` ends with exit 42 (Publish-Remote Gate)](#publish-ends-with-exit-42-publish-remote-gate) - [Setup or an update fails, and you want to report it](#setup-or-an-update-fails-and-you-want-to-report-it) ## `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. ## `doctor` reports `telemetry: WARN` The `telemetry` section of `.wikitool-local.json` holds something telemetry does not read as written: an unreadable settings file, a value that is not an object, an `enabled` that is not `true` or `false`, a cap that is not a positive whole number, or a key it does not know. Telemetry itself never stops on this. It ignores the file or the value, or reads `"no"` as on, and the line names the field. Correct the section to the shape in the [configuration reference](../reference/configuration.md#telemetry), or remove it to get the default back. ## `new` stops with "No author configured" Neither `$WIKI_AUTHOR` nor `git config user.name` is set. Run `git config user.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 ` 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 `remotes.allowed_push_urls` list in `.wikitool-local.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 that list yourself. An agent that edits the list 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-/`, 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. - **Correcting the chronology afterwards:** if the chronology turns out wrong or missing once the bundle exists, the agent swaps it with `tools/bugreport --bundle … --chronology …` instead of collecting again. That changes only `CHRONOLOGY.md` and the zip - no `wikitool` command runs again and no second bundle appears - and the new text is scrubbed, kept clear of titles and pseudonymised like the rest. After a stage 2 run the agent reads the new chronology and runs stage 2 once more for names it finds there. Nothing is uploaded anywhere. You choose the channel.