Troubleshooting

Troubleshooting

Symptom-first troubleshooting for every tool in the kit, built from the exact error strings the sources emit (read at commit 7e17a11) and the incidents documented in setup/PITFALLS.md and CHANGELOG.md. Find your message in the tables, follow the fix, and if nothing matches, work the diagnostic ladder at the bottom. Messages are quoted verbatim where quoting is safe; where a message contains phrases this wiki's own ban list would flag, the wording is paraphrased and the source line given.

Contents

• Environment and bootstrap
• Staging and probing
• Auditing (qa_wiki.py)
• fix_toc.py
• Publishing and git
• Sandbox filesystem weirdness
• Diagnostic ladder (when nothing matches)
• See also

---

Environment and bootstrap

Symptom	Cause	Fix
E: Unable to locate package php-cli (or any package)	fresh sandbox with empty package lists (PITFALLS B1)	apt-get update first — bootstrap.sh does this as step 1; run it instead of hand-installing
FAILED: <label> (see /tmp/apt-<label>.log) in the bootstrap output	a specific install failed	read the named log; on non-apt systems install the equivalent manually and re-run — bootstrap is idempotent and skips what exists
bootstrap step 7 prints ✗ refusing to continue: probing a subject the runtime cannot boot and exits non-zero	--subject runtime-floor gate tripped (B10)	install a runtime that satisfies the subject's floor (the PHP path: Sury recipe printed by --with-php83 and in PITFALLS B10), then re-run
RUNTIME MISMATCH: the subject needs >=8.3; found php 8.2.34. It will NOT BOOT, so every probe would measure a corpse	check_runtime.py exit 2	as above — do not "try anyway": every finding would be fiction
composer install prints a package-download warning then the full usage screen	missing unzip/ext-zip (B9) — the output reads exactly like a wrong-flag error	apt-get install -y unzip (and php-zip when the subject uses ZipArchive), then re-run
probes all return 500 or an error page	interpreter cannot boot the subject (parse error on the runtime's syntax)	run check_runtime.py; check ServedApp.server_log() — a staged server's log carries the interpreter's complaint
curl: command not found at session start	some sandboxes ship without curl (B2)	bootstrap.sh installs it; until then use lib/req.py — stdlib-only and it returns headers+status+body as data
pkill/pgrep/lsof/ss not found	minimal sandboxes (B3)	the Python socket-bind probe from PITFALLS B3 finds port holders; serve.py tracks and kills its own children

Staging and probing

Symptom	Cause	Fix
RuntimeError: port 8080 on 127.0.0.1 is already in use … Do NOT proceed: requests would hit the other server.	a previous experiment still holds the port — the A1 trap	this raise is the fix working. Kill the stray (`ps -eo pid,args
tests "pass" but results contradict the code you just read	you are talking to a stale server with an old docroot/state (A1, the worst offender)	never hand-roll php -S &; use ServedApp — clean staged copy, verified-free port, readiness probe, teardown
TimeoutError: server on 127.0.0.1:PORT did not become ready in 20.0s	the server command dies on start (missing binary, bad template, boot error)	the failure dumps the server log automatically — read it; check --serve-cmd substitution ({host} {port} {root})
RuntimeError: server accepted TCP but no HTTP response	port opened but the interpreter dies on every request (missing extension, parse error)	same: the dumped log has the interpreter's error; install the extension or fix the subject's floor (B10)
FileNotFoundError: source is not a directory: …	wrong --repo path	point at the cloned subject directory, not a file
ModuleNotFoundError: No module named 'http.client'; 'http' is not a package	a local file named http.py (or json.py, re.py, …) shadows the stdlib (A2) — the error names the stdlib, so it misleads	rename your helper; keep helper modules in lib/ with collision-proof names
probe JSON is empty / evidence file missing after a long run	the final write hit a filesystem hiccup (B11)	write evidence through lib/evidence.write_evidence() — it retries into <kit>/workspace-fallback/ and prints a diagnosis; check that directory before re-running
battery_flags records {"error": "battery_flags needs --repo (a staged instance) to mutate config"}	flag battery run against --base-url	config mutation requires a staged copy: use --repo
AssertionError: php-mdviewer suite requires --repo	suite/CLI mismatch	as above
❌ EXPECTED 301 (or any expectation mismatch) in the probe summary	documented expectation vs measured behaviour diverged	investigate, do not delete: either the subject drifted (record it as a finding — this wiki's run found two such drifts) or the fixture state differs from the recorded run (e.g. a redirect target absent from the staged docroot)
every path returns 200	front-controller fall-through: the router serves the home page for unknown paths	assert on body markers, not statuses — the run-2 rule; see Research and Probing Guide
login/admin branch fails as a cascade of 403s	a CSRF token shape was missed, or the token was sent in the URL	csrf_from_html covers six shapes — extend extra_patterns; tokens go in the body field and a header, never the query string (lib/session.py does this by design)

Auditing (qa_wiki.py)

Structural errors, with the fix each message implies:

Message fragment	Fix
[[X]] → no such page (did you mean the file "X.md"? name files with SPACES)	the hyphenated twin exists: rename the file to spaces; never rename the link to hyphens (C1)
[[Page#frag]] → anchor not found in Page.md	run fix_toc.py and copy the computed slug; anchors follow GitHub's algorithm, including non-collapsed double hyphens (C5)
_Sidebar.md does not link every page. Missing: [...]	add the missing [[Page]] entries — sidebar coverage is a contract
_Footer.md is absent (warning)	add one; it renders on every page and carries the verified-commit line
expected exactly one H1, found N	demote extra # headings to ##
missing a "## See also" section	add the section with cross-links
invalid GitHub Alert type [!X]	only NOTE, TIP, IMPORTANT, WARNING, CAUTION exist; anything else renders as a blockquote with visible [!X]
fence nesting: a 3-backtick block opened at line N is closed early … Wrap the outer block in 4 backticks	do exactly that (C7) — this bug shipped once and rendered the rest of a page as garbage
unterminated code fence	close it; every heading and link after an open fence is swallowed
mermaid#N: unbalanced [] / odd number of double quotes / label contains brackets but is not quoted	quote labels with special characters; balance brackets (C6)
mermaid#N: bare '&' in edge label	write & — GitHub's renderer requires the entity
mermaid#N: K 'subgraph' vs M 'end'	balance block keywords; remember end means different things in flowcharts vs sequence diagrams (the checker is kind-aware, so a hit is real)
bash block #N fails bash -n: <first error line>	fix the snippet; if it is a transcript/output, re-tag the fence text so the checker skips it honestly
python block #N does not compile: line L: <msg>	fix the snippet; REPL transcripts with >>> are skipped automatically
marketing filler 'x'	cut it; domain terms get a fluff_exemptions entry with a reason
banned claim 'x' — reason	the claim is false/unverifiable: rewrite; refutations get paraphrased, never quoted (C8); legitimate hits get exemptions (INFO)
avoided term 'x'	use the canonical term; verbatim subject strings and filenames win — narrow the pattern, log it in _tuning_log
warning possible NEGATED mention of banned phrase	working as designed: review the sentence, do not "fix" the checker — negations downgrade, never suppress

Meta-problems:

Symptom	Cause	Fix
hundreds of errors of one family on a healthy wiki	the checker itself is wrong (it happened three times: 381, 12, 235 phantom errors)	verify one case by hand before believing a mass failure (D2); run --self-test — if it fails, fix the checker before the wiki
clean run feels suspicious	a checker that cannot fail proves nothing	--self-test (22 detections) is the proof; run it once per session
--ban … no active phrases (warning)	every top-level key in ban.json starts with _	promote the real phrases out of _template_delete_me to top-level {phrase: reason} keys — a silent no-op would let you believe bans are enforced
ban/avoid fires on a code span, filename or anchor slug	you are on a pre-1.2.0 checker	update: matching runs on the scrubbed view since 1.2.0 (code, links, anchors, filenames blanked)

fix_toc.py

Symptom	Cause	Fix
skipped: no "## Contents" block	page lacks the section	add ## Contents (the scaffold emits it); the tool only replaces the list under that heading
worried it will eat surrounding prose	an earlier TOC regenerator did exactly that (D8)	this version is block-scoped with a word-count guard and --bak; its self-test fixture is the accident — run --self-test (8/8) to see lead/badge/alert survive
TOC anchors still failing QA after a fix	stale derived data (D1)	re-run fix_toc.py then the auditor; never reuse an old anchor map after renames

Publishing and git

Symptom	Cause	Fix
clone failed (private repo, no network, or the wiki has never been initialised)	GitHub creates .wiki.git only after the first UI page save	open https://github.com/OWNER/REPO/wiki, click "Create the first page", save — then re-run; or take the fallback the script already prepared (local init + bundle) and push later
QA failed. Fix the errors above, then re-run.	the step-1 gate did its job	fix the audit errors; the gate is not bypassable by design
push failed — almost always missing credentials	sandboxes have no credential prompts (B6)	expected: use the hand-over — PUBLISH.md lists three publish options (push the prepared clone, pull the bundle, copy the files)
warning: remote HEAD refers to nonexistent ref, unable to checkout + empty tree when cloning a bundle	bundles carry no HEAD symref (B8)	git clone -b master REPO.wiki.bundle outdir — and distrust any check that "passed" against the empty tree
fatal: refusing to merge unrelated histories	kit-built repo and existing GitHub repo have different roots	git merge --allow-unrelated-histories --no-edit FETCH_HEAD; resolve the add/add conflicts (typically .gitignore, README.md)
committed, pushed — but files are missing from the remote	an ignore rule silently dropped them on the copy path (the Python template's bare lib/ rule)	deep-check git ls-files against the intended tree; git diff --cached --diff-filter=D --name-only must be empty before committing; bundle-merges do not hit this trap
prepared clone lost its origin after a workspace reload	snapshots exclude .git/config (A3)	publish.sh re-adds origin on the fallback path; otherwise re-add manually — the remote URL is in PUBLISH.md
pushed to main but the wiki did not change	wiki repos publish the default branch: master (C2)	push to master; delete the orphan main if you created one

Sandbox filesystem weirdness

Symptom	Cause	Fix
a script's find/glob on an absolute workspace path returns nothing, while the same command typed at the shell works	harness path rewriting: command strings get the workspace variable substituted; file contents do not — the script's literal path points outside the real workspace (B4-class; found in the wild during this wiki run)	inside script files resolve at runtime (WS="${ARENA_WORKSPACE:-/home/user}"); prefer relative paths after cd; pass paths via env vars
files "disappear" between sessions	written outside the persistent root (/tmp) or into snapshot-excluded dirs (dist/, build/, out/, caches) (A3)	keep everything under the workspace; never place deliverables in excluded directories
open() fails with a mangled path containing an unexpanded variable	heredoc path mangling (B4)	cd first, or env vars, or write the script to a file and run it
results differ between two runs seconds apart	call-scoped filesystem views in some sandboxes	re-run in a fresh call before debugging the code; record the artefact in REWORK-STATE.md either way
output paths look wrong but commands work	display-layer rewriting of captured output	encode outputs (base64) to see raw bytes when diagnosing

Diagnostic ladder (when nothing matches)

1. Read the error literally; then check this page's tables once more for the family of the message.
2. Verify one failing case by hand — mass failures are checker bugs until proven otherwise (D2).
3. Re-run in a fresh process/call — some environment artefacts are call-scoped.
4. Check the layer between you and the filesystem/network (path rewriting, mounts, egress) — see Sandbox Survival Guide.
5. bash setup/snapshot.sh workspace "before debugging" — then experiment; never destructively.
6. If you find a new trap: append it to REWORK-STATE.md's quirks section during the run, and propose it for PITFALLS.md upstream — the document is an append-only ledger of exactly such discoveries.

---

See also

• Sandbox Survival Guide — the PITFALLS taxonomy behind these tables
• QA and Audit Guide — interpreting audit output in context
• Tool Reference — exit codes and flags for every tool
• Publishing and Delivery — the git flows in full
• Research and Probing Guide — probe failure modes at the source