Debugging a Failed Thread

Goal. Diagnose a failed, paused, or stuck thread quickly and collect enough evidence for a deterministic fix.

When to use. A run reports failed or cancelled, output is missing or truncated, or a thread sits in running/pending without progress.

1. Fast triage (CLI)


# Status, error, and current step
dodil scriptum thread get thr_fail_01
 
# Full result payloads to disk for offline analysis
dodil scriptum thread result thr_fail_01 --save ./debug/thr_fail_01
 
# Step-level detail: per-step input/output, errors, execution IDs, logs URLs
dodil scriptum thread steps thr_fail_01 --detail
 
# Confirm the service and your auth are healthy
dodil scriptum health
dodil scriptum doctor

thread steps --detail is the workhorse: it shows each step’s primitive, tool, status, duration, truncated input/output, any error, and the execution ID or logs URL the runtime attaches.

2. Focus on the failing step

Once thread get or the step table tells you which step failed (for example 1.3.0), pull just that one:


dodil scriptum thread steps thr_fail_01 --step 1.3.0

If you need the raw result of a single step programmatically, query it through the API:


grpcurl \
  -H "authorization: Bearer $DODIL_TOKEN" \
  -H "x-organization-id: $SCRIPTUM_ORG_ID" \
  -d '{"thread_id":"thr_fail_01","step_path":"1.3.0"}' \
  rpc.dev.dodil.io:443 dodil.scriptum.v1.ScriptumService/GetThreadResult

3. Decision tree

Stuck in pending/running with no progress — re-watch with thread watch; check health/doctor for a transient connectivity problem.
Failed fast — inspect the failing step’s input and error in thread steps --detail; check that required env values resolved (run with --env).
Output truncated or incomplete — re-fetch with thread result --save, which streams the full payload.
Paused and cannot continue — validate the resume payload against the pending input contract; see Human-in-the-Loop Resume.

4. Evidence to collect before fixing

Thread ID and script version
The input payload used
Result summary and complete output (thread result --save)
Step-level detail and the failing step path
health/doctor status at incident time

5. Stabilization loop


# Patch the draft, then re-validate and re-test
dodil scriptum draft save invoice-parser -f ./invoice_parser.scriptum
dodil scriptum draft compile invoice-parser
dodil scriptum draft test invoice-parser --input @./debug/thr_fail_01/output.json --env
 
# Publish the fix and re-run the failing input
dodil scriptum draft publish invoice-parser
dodil scriptum thread run invoice-parser --input @./debug/repro.json --result --save ./out/fix-verify

Close the incident with the attached artifacts and the new version number.