torbenandClaude Sonnet 5.5
b48a35b224
Files changed: - CHANGES.md - VERSION - docs/how-to/troubleshoot.md - instructions/bug-report.md - tools/README.md - tools/bugreport.py - tools/chemenu/tests/test_bugreport.py Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
119 lines
6.4 KiB
Markdown
119 lines
6.4 KiB
Markdown
# 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).
|
|
|
|
<!-- wikitool:toc -->
|
|
## 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)
|
|
<!-- /wikitool:toc -->
|
|
|
|
## `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 "<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 `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-<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.
|