Troubleshooting¶
Symptom, cause, fix. Most entries come from building the course-builder example on small local models.
| Symptom | Cause | Fix |
|---|---|---|
Model keeps running edit view on the same file, then writes invented data |
Old observations fold after 2 turns (#27) | Give it one compact tool view right before the write, ending with the exact next call. See Context and SQLite Store |
A long edit write is missing a whole section |
One big generation drops content | Write one small file per section (part-N.md) and join them with a tool. Same page |
Earlier file content vanished after a second edit write |
edit write replaces the whole file (#34) |
Tell the model to rewrite the complete file, or use edit replace --lines. See Built-in Tools |
Files contain a literal \n |
Model sent escaped newlines in stdin | Fixed in v0.1.2 for edit write, edit replace and done |
Tool with multi-word argument fails (unexpected keyword argument, wrong value) |
Unquoted words were not joined | Fixed in v0.1.2. See argument parsing |
Error: unknown command for a tool defined in tools.py |
The tool is not in the skill tools: list (#24) |
Add its name to tools:. See Skills |
Gate with inline awk/sed is blocked as "absolute path outside workspace" |
Fixed in v0.1.4 (#31); older versions saw a program starting with / as a path |
Upgrade, or move the logic into a script (python3 checks.py ...). See Security and Sandbox |
| Gate exits 0 although work is missing | Missing input file means nothing to check | Make the gate fail closed. See Gates |
Session FAILED after 3 gate failures, none of them real |
A gate environment error counts as a failure (#33) | Run the gate command by hand first |
| Model repeats a tool call with a rejected value | Gate or tool message says what failed, not what to do | Return the valid options and the next call in the message. See Custom Tools |
| A pipe-delimited file gets extra or shifted columns | A delimiter (|) appeared inside a value |
Sanitize values in the tool that writes the file |
| Pipeline stage ends "Max steps reached" | max_steps too small for the work (#35) |
Raise max_steps (pipeline or stage), or re-run the stage's skill by hand. See Pipelines |
| A thinking model loops and the trace shows no reasoning | Reasoning is not recorded (#32) | Inspect the commands with the telemetry query; try a non-thinking model |
Known limitations¶
- #24 skill
tools.pytools must also be listed intools:. - #27 observation folding hurts small models.
- #32 model reasoning is not in the trace.
- #33 gate infrastructure errors count toward the 3-failure abort.
- #34 no
edit append. - #35 no pipeline resume; one
max_stepsfor the whole pipeline unless set per stage.
Model notes¶
In this experiment gemma4:e4b needed much more scaffolding (numbered-candidate tools, joined views, tight gates) than qwen3.5:9b. These were single runs on a small sample, so treat this as an observation, not a benchmark.