Skip to content

Troubleshooting

Jump to bottom
Chris Sweet edited this page Jul 14, 2026 · 1 revision

type: reference up: "What-is-the-llm-wiki-Template" related:

Troubleshooting

Recovering from common failure modes. Grounded in ensure-wiki.py, scripts/kg/, the write protocol, and the lint/verification procedures. Where a recovery is general git practice rather than a template-specific mechanism, that is noted.

The wiki is not loading at session start. What do I check?

The SessionStart hook (ensure-wiki.py) clones the wiki from the GitHub wiki URL derived from your origin remote. Check, in order: (1) does the project have an origin remote, and is it a GitHub host? The hook is GitHub-only and exits quietly on other hosts. (2) Has the wiki's "Home" page been created in the GitHub wiki tab? A GitHub wiki does not exist as a clonable repo until its first page exists. (3) Is the clone reachable non-interactively (no credential prompt, private-repo access set up)? The hook runs with a 30-second timeout and GIT_TERMINAL_PROMPT=0, so it will not hang; it falls back to a message asking the agent to clone. (4) Is python3 on PATH? The hook is registered behind a command -v python3 guard and silently no-ops without it. Manual fix: git clone https://github.com/<owner>/<repo>.wiki.git wiki/<repo>.wiki.

The graph build failed. What is the first thing to look at?

Dependencies. scripts/kg/build-graph.sh needs Bash 4+ and Python 3 with PyYAML, rdflib, and pyshacl. A missing package is the most common failure (see the arq/rdflib question below). Next, check that the wiki path is right (--wiki=PATH if non-default) and that the spec fetch succeeded (the pipeline fetches the LA3D ontology/SHACL spec and caches it; --refresh-spec re-fetches). Run with --stats to see extractor coverage. Note the build does not abort on SHACL violations, so a "failure" is usually a dependency or path error, not a validation error.

The LLM keeps writing pages without asking. How do I slow it down?

Proactive writing is the intended default (the wiki-maintenance rules tell the agent to write without being asked, and to commit without asking because local commits are reversible). If you want approval-first behavior, say so: instruct the agent to propose changes before writing, or work in a mode where you invoke the operations explicitly via the slash commands (/wiki-source, /wiki-experiment, /wiki-lint) rather than relying on proactive behavior. You can also soften the ## Wiki maintenance behavior guidance in your CLAUDE.md (keep edits outside the template's sentinel blocks so updates do not revert them). The commits are local and reversible, so over-eager writes are cheap to undo with git -C wiki/<repo>.wiki reset.

I have a merge conflict on the wiki. What is the safe recovery?

Index and log conflicts should not reach you: .gitattributes merge=union merges them mechanically. For a genuine content conflict on a page, the safe path is the write protocol's model: the conflicted file sits on disk with markers; read both sides, decide drop / adapt / supersede, write the merged content, git add and commit, then re-run the push. If you are mid-wiki_push and hit the retry cap, your un-pushed commits are preserved on local main; inspect them, then retry, reset to abandon, or cherry-pick to a clean state. See Team-Workflow.

The wiki has grown too large to browse. How do I archive old content?

There is no built-in archival command; this is a manual, git-native operation. Options: move superseded pages into an archive/ subdirectory (updating up: and cross-references so nothing dangles), or mark stale pages with a note pointing at the superseding page during a lint pass rather than deleting them. Because it is git, deletion is never lossy: history retains anything removed. Practically, lean on the index categories and hubs for navigation rather than trying to browse every page; the index-first read path is designed for exactly the "too many pages to eyeball" case.

The LLM is citing pages that no longer exist. What happened, and how do I fix it?

A page was renamed or removed but an inbound link or index entry was not updated, leaving a dead link the agent then "cites". This is the classic lint finding. Fix: run /wiki-lint, which scans for dead links and index gaps and repairs them (or fix the specific link target by hand). The verification gate is supposed to catch this at write time (every body link must resolve to an existing page), so a dead link usually means a write skipped the gate; a lint pass cleans it up and a log entry records the fix.

SHACL validation is failing. What is a shape violation and how do I read the report?

A shape violation means a page's frontmatter does not satisfy a SHACL shape from the fetched shapes.ttl: a typed edge pointing at the wrong kind of target, a missing required field, or a node type the shapes constrain. The report is written to scripts/kg/build/validation-report.ttl as RDF Turtle; read it for the focus node (which page), the path (which predicate), and the constraint that failed. Because the build does not abort on violations, a failing report is advisory: it tells you which pages to clean up, not that the graph is unusable. Fix the offending frontmatter and rebuild. See Knowledge-Graph.

I accidentally committed private content to the wiki. How do I unwind?

If you have not pushed, the commit is local and reversible: git -C wiki/<repo>.wiki reset (soft to keep the file changes, hard to discard) before it ever leaves your machine, this is why the template keeps pushes explicit and commits local by default. If you have pushed, treat it as a leaked secret: rotate anything sensitive (assume it was seen), then rewrite history (git filter-repo or equivalent) and force-push, coordinating with any other writers since a force-push diverges their clones. Prevention: keep secrets and private data out of the wiki entirely (see Best-Practices).

The SessionStart hook did not clone the wiki. What do I do?

Same causes as "wiki not loading" above: non-GitHub origin, wiki Home page not yet created, unreachable/private clone, or missing python3. The hook is designed to fail quietly and fall back to a nudge rather than block your session, so a silent non-clone is expected under those conditions. The manual remedy is the explicit clone: git clone https://github.com/<owner>/<repo>.wiki.git wiki/<repo>.wiki. If the wiki is present but stale, the hook fast-forwards it only when the checkout is clean; local uncommitted changes make it skip the update, so commit or stash them.

arq or rdflib is not installed. Which error indicates which?

Important correction: the template's KG pipeline uses rdflib + pyshacl in-process Python, not arq (arq is Apache Jena's SPARQL CLI). So on the default path you should only ever hit an rdflib/pyshacl/PyYAML error, which surfaces as a Python ModuleNotFoundError (or ImportError) naming the missing package; fix with pip install rdflib pyshacl pyyaml. You would only encounter an arq "command not found" if you opted into the Fuseki/Jena path (multi-client endpoint, SPARQL UPDATE), which is not the default and which you set up separately. If you see arq: command not found, you are on the optional Jena route; if you see a Python module error, you are on the default rdflib route.

See also

Clone this wiki locally