Skip to content

Chapter 14 — Troubleshooting

The final chapter. When something breaks, this is your lookup. Unlike the earlier chapters, this one isn't linear — jump to the section that matches your symptom.

Chapter at a glance

flowchart TD
    A[Something<br/>broke] --> B{What kind<br/>of failure?}
    B -->|Import error| C[PatchWork<br/>import bugs]
    B -->|Generation issue| D[Generation<br/>failures]
    B -->|Runner crash| E[Runner crash<br/>recovery]
    B -->|Cache stuck| F[Cache wipe /<br/>force re-roll]
    B -->|Unclear| G[Common errors<br/>lookup table]

Diagnostic lookup, not a procedure. Jump to the matching symptom.

What you'll find here

  • Common errors — symptom → cause → fix tables for the most frequent failures
  • PatchWork import bugs — the catalog of r.trim is not a function causes and their fixes
  • Generation failures — what to do when the runner produces wrong / broken / unusable outputs
  • Recovery procedures — restoring from backups, force re-rolls, cache wipes

When to come here

  • A Generation Runner pass surfaced errors
  • A .nbflow won't import into PatchWork
  • Outputs look wrong despite a clean sanity check
  • A workflow that used to work suddenly doesn't
  • The G-Labs tunnel dropped mid-run

Sections

  1. Common errors — symptom → cause → fix lookup table
  2. PatchWork import bugs — every known r.trim cause with a fix
  3. Generation failures — diagnostic flow + fixes for bad outputs
  4. Runner crash recovery — restore + cache-aware re-run after a mid-pass failure
  5. Cache wipe / force re-roll — explicit cache control when the cache is in your way

Where to go after troubleshooting

Try this

This chapter is reference, not a procedure to practice. Your "assignment" is the next time you hit a real failure:

Steps:

  1. Note the exact symptom (error message, what you ran, what you expected, what actually happened)
  2. Open this chapter's section that matches the symptom — Common Errors first, then the specific category (import / generation / runner crash / cache)
  3. Apply the fix. If it works, you're done
  4. If it doesn't work, add the symptom + fix to the relevant page. Future-you will thank you

This chapter only stays useful if the people hitting failures contribute back. Treat every novel failure as a chance to extend it.

If the failure isn't in here at all:

  • It's a new failure mode → file an issue with a link back to this chapter, then add a stub to Common errors
  • The failure is in the agents themselves (logic bug, wrong rule applied) → that lives outside the wiki, in the agents' own definitions. Flag it in the manager repo

You've reached the end of the linear path. Going forward, treat the wiki as reference — jump to the relevant chapter when you have a question.