torben/chemenu
1
1 Fork 0
Code Issues 40 Pull Requests Actions Packages Releases 41 Wiki Activity
Page: How to Troubleshoot
Pages
Dev Development Explanation Architecture Explanation Configuration tiers Explanation Knowledge and commitment Explanation Language boundaries Explanation Model and effort selection Explanation Ownership and templates Explanation Pipeline rationale Explanation Telemetry and evaluation Explanation Version model Explanation Why gates are code Explanation Home How to Back up to a synced folder How to Browse with obsidian How to Capture repository docs How to Collect from a synced folder How to Export guidelines How to Export to a synced folder How to Fetch pages behind a login How to Ingest a source How to Maintain the wiki How to Query the wiki How to Run the weekly review How to Set up the mcp server How to Trace and score sessions How to Troubleshoot How to Update an instance How to Use 1password for settings How to Write a site handler How to Install Reference Commands Catalog and log Reference Commands Configuration Reference Commands Content migrations Reference Commands Distribution and versioning Reference Commands Exports Reference Commands Finding and checking Reference Commands Git Reference Commands Instance health Reference Commands Links and citations Reference Commands Pages Reference Commands Provenance Reference Commands Raw material and uploads Reference Commands Telemetry Reference Commands Types instructions and docs Reference Commands Workshop runs and session budget Reference Commands Reference Configuration Reference Exit codes Reference Page types Reference Skills Reference Tutorials First source to first answer Tutorials Sample source Tutorials
Clone
3
How to Troubleshoot
Wiki Mirror edited this page 2026-10-16 14:43:37 +00:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Generated from docs/how-to/troubleshoot.md at v10.1.0 – edit the repository, not this wiki.

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