# /zibby-debug — diagnose a failing or stuck Zibby workflow You are helping the user debug a workflow that didn't behave as expected. Canonical docs: **https://docs.zibby.app/workflows/debugging** ## Diagnostic recipe Apply in order. Stop at the first thing that explains the symptom. ### 1. Did the deploy succeed? ``` zibby agent list ``` Find the workflow. If `bundleStatus` isn't `ready`, the deploy didn't finish. Re-run `zibby agent deploy --verbose` and read the build output. ### 2. Did the trigger reach the runtime? ``` zibby agent trigger ``` Look at the response — it should include a `Job ID` immediately. If you get an HTTP error, it's an auth or quota problem (build concurrency, run-concurrency caps, etc.). Surface to the user. ### 3. Did the agent task START? ``` zibby agent logs -t ``` Within 30s of the trigger you should see `[setup] Fetching bundle...` then `zibby v`. If silence past 30s: - Maybe the runtime couldn't start the task — a platform-side issue; retry, and report it if it persists - Maybe the task started but its log stream is delayed — wait another 30s - Maybe the workflow row hasn't been written yet (rare — would only affect the very first second) ### 4. Did the workflow execute the wrong path? If the tail shows nodes running but in unexpected order, your `graph.mjs` edges are wrong. Common causes: - Edge from `START` is missing — first node never runs - Cycle in the graph — runtime errors with "cycle detected" - Node id in `nodes/` array doesn't match the file's exported `id` ### 5. Did a node fail? The tail will show `Error: Node '' failed: `. Common reasons: - Agent (LLM) returned malformed output that didn't match the node's `outputSchema` - Node code threw an uncaught exception - Shell command in the sandbox returned non-zero For agent errors, look for `│ Prompt sent to LLM:` and `│ Response:` blocks in the tail. The model's reply is right there. ### 6. Did the task die without finishing? Look for `[fanout] hard timeout` in the tail — means the task ran past the cap. Or the status stays `running` indefinitely (zombie row). Re-trigger. ### 7. Are you seeing logs from a stale execution? `-t` on a workflow UUID auto-attaches to the **latest** existing execution at connect time, plus new ones triggered while it's open. If you're tailing an old failed run, drain it (Ctrl+C, re-run after triggering fresh). ## Quick reference: what each piece does - **Trigger** → records the execution + spawns a sandboxed task - **Task** → fetches the bundle, runs `node graph.mjs`, streams logs, and updates execution status as it progresses - **SSE fan-out** → the log-streaming service; fans events out to subscribers (`-t` clients) - **Status** → moves through `starting → running → completed/failed/error` If the stored `status` is wrong (e.g. stuck `running` after the task is gone), it's an upstream zombie — separate from any workflow logic issue.