chemenu/docs/how-to/troubleshoot.md

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 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.

Contents

• tools/wikitool ends with STOP - this checkout is not set up yet (exit 42)
• The agent offers no skills (wiki-ingest, wiki-query, ...)
• doctor reports personalization: FAIL
• doctor reports environment: WARN
• doctor reports telemetry: WARN
• new stops with "No author configured"
• publish ends with exit 42 (Mass-Update Gate)
• publish ends with exit 42 (Publish-Remote Gate)
• 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:

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 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:

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. 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, 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 "<Name>", or export WIKI_AUTHOR (configuration).

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 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, 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.

• 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.