Troubleshooting

Troubleshooting

First moves, always

curl -s http://127.0.0.1:8765/health      # version, git_sha, started_at

• A stale git_sha means the process predates the code — codingdude restart.
• A version mismatch between the StatusFooter's ui and srv means a stale frontend/dist — rebuild it and hard-refresh the browser.
• ~/.codingdude/logs/server.log and worker-*.log hold the actual error.

Common symptoms

Symptom	Cause and fix
401 on API calls	Wrong or absent token. Browsers: reload the UI (the same-origin cookie re-issues). Scripts: Authorization: Bearer <token> from ~/.codingdude/server-token
Provider key rejected at run start	Verify keys in the Config panel catches this before a run. Z.AI coding-plan keys need fallback_base_url = "https://api.z.ai/api/coding/paas/v4"
Model errors at run start	Check the Config panel warnings and the provider's endpoint/plan; a zai: fallback without the coding-plan URL is the classic
Run "still working" forever	Check the Waterfall for the hung span, then Stop. The worker watchdog and janitor handle the known classes; logs will name the worker
New code or fix not in the UI	Rebuild frontend/dist; hard-refresh (cached bundles are a classic). Config changes never need a rebuild
Config edits not taking effect	They apply from the next run
Agent edits the wrong project	A session is bound to a workdir — check the StatusFooter; a ⚠ means the session is not in the selected project
Drive-relative path rejected	Use G:\path, not G:path
A gated command never runs	That is the design: approve it, or pass --yolo. Headless runs exit 2 and print the command
Bash not found / WSL errors	bash resolves to Git Bash explicitly on Windows; install Git for Windows
uv run changes my environment	uv run is a mutator: it re-syncs the venv when the lock and environment disagree. Use the venv's binaries directly for read-only probes
Port already in use	codingdude serve --port <n>; 4318 is usually an OTLP collector, not CodingDude

Spend stops

Symptom	Meaning
run stops with a message naming cost_limit / token_limit	the [models] per-call ceiling fired — this is the intended hard stop
CostNotFoundWarning in the logs	max_cost_usd cannot be enforced because the model has no configured price — set max_total_tokens
exit code 3 from codingdude run	the session Budget Cap (--budget) was exceeded
a delegation aborted early	[delegation] max_requests / max_cost_usd slice exhausted; the message names the limit that fired

Context and compaction

Symptom	Meaning
CONTEXT_COMPACTED in the trace	the per-request guard fired — normal, not an error
provider context-length 400	the window is misconfigured: set [models] context_limit to the real value
the agent forgot earlier turns	compaction summarised them; that is the trade. Keep decisions in project notes or memory instead of chat
caching seems off	providers with implicit caching ignore prompt_cache (correct no-op). A bad prompt_cache_settings key fails at boot, not silently

Review gate

Symptom	Meaning
git_push refuses, naming a missing/stale review	record a two-axis review of the current diff (Review Gate)
the record was valid five minutes ago	the diff changed — any edit or fix voids it, by design
"the recorded review covers branch X"	records are branch-scoped; record on the branch you are pushing
git push in a shell command refused	deliberate: use the push tool so the gate can see the review

Planning store

Symptom	Meaning
status select shows an unknown value	an unknown stored value still renders and keeps its entry rather than blanking
ROADMAP.md shows a large formatting diff	writing through the planning tools normalises the document — expected
an old ticket's closing commit does not resolve	squash-merge rewrote it; repoint the reference at the squash commit
a ticket will not close as done	steps lack evidence or ran out of order; supply structured evidence or record an explicit waiver

Frontend

Symptom	Fix
blank page	check the console; a stale dist or a failed npm run build is usual
a panel shows a placeholder	no session selected — that is the empty state, not a bug
user text rendered as an option object	the ask_user payload must use plain string labels; the tool rejects other shapes with a concrete fix

Getting help

• Setup / configuration — Discord.
• Reproducible bugs — open an issue with the /health output, the relevant worker-*.log lines, and what you expected.
• Security — never publicly; follow SECURITY.md.

A bug report with the gate output that proves it is worth ten without.