Free SKILL.md scraped from GitHub. Clone the repo or copy the file directly into your Claude Code skills directory.
npx versuz@latest install kineticdata-kinetic-platform-ai-skills-skills-commands-kinetic-debug-rungit clone https://github.com/kineticdata/kinetic-platform-ai-skills.gitcp kinetic-platform-ai-skills/SKILL.MD ~/.claude/skills/kineticdata-kinetic-platform-ai-skills-skills-commands-kinetic-debug-run/SKILL.md---
name: kinetic-debug-run
description: Debug a Kinetic workflow execution — find failures and diagnose root causes
argument-hint: "[run-id or 'last failed']"
user-invocable: true
---
# Debug a Workflow Run
The user wants to debug a workflow execution. They may provide a run ID, or say "last failed" / provide no argument (find recent failures automatically).
## Step 1: Connect
Connect to the Kinetic Platform using `mcp__kinetic-platform__connect`.
## Step 2: Find the Run
**If run ID provided:** proceed to Step 3.
**If no run ID or "last failed":**
1. `list_triggers` with `status=Failed`, `limit=10`, `include=details` — find recent failures
2. Show the user a summary of recent failed triggers with run IDs, tree names, and timestamps
3. Ask which run to investigate (or auto-select the most recent)
## Step 3: Get Run Details
1. Get all triggers for the run: `list_triggers` with `runId={id}`, `include=details`
2. Note: Run status is always "Started" in the API — derive real status from triggers:
- All triggers Closed → run completed successfully
- Any trigger Failed → run failed
- Any trigger with status New/Work In Progress → run is still executing or stuck
## Step 4: Analyze Triggers
For each trigger, check:
- **Status** — Closed (success), Failed (error), New (not started), Work In Progress (executing)
- **Node name** and handler — what was it trying to do?
- **Duration** — how long did the handler take?
- **Error details** — in the trigger's details/messages
## Step 5: Diagnose Common Failures
### ENGINE Run Error
The workflow engine itself failed to execute a node. Common causes:
- **Wrong Return node params** — WebAPI trees need `content, content_type, response_code`; event trees need `status, description`. Using the wrong set causes this error.
- **`system_return_v1` doesn't exist** — must be `system_tree_return_v1`
- **Wait param case sensitivity** — must be `"Time to wait"` and `"Time unit"` (caps + spaces), NOT `"time_to_wait"`
### Missing Handler Error
- Handler definition ID is wrong or handler is not installed
- `system_return_v1` → should be `system_tree_return_v1`
- Check handler exists: `list_handlers` and search for the definition ID
### Node Silently Missing
- **Duplicate node ID suffixes** — if two nodes share the same suffix (e.g., `utilities_echo_v1_1` and `system_wait_v1_1`), the builder drops one silently
- Export the tree and check for duplicate suffixes
### Stuck Run (triggers stay New/WIP forever)
- Start node may be stuck — manually advance with:
`POST /app/api/v2/runs/{runId}/triggers` with `{"nodeId":"...","action":"Root","type":"Automatic","loopIndex":"/"}`
### Connector Condition Failures
- Connector `value` is a Ruby expression — check syntax
- Empty value = unconditional (always fires)
## Step 6: Check Related Resources
- **Active errors:** `list_triggers` with `status=Failed` across all runs for the same tree
- **Tree definition:** `get_tree` with `include=treeJson` (export endpoint may be broken — use this instead)
- **Handler details:** `get_handler` with the failing node's `definitionId` to check expected parameters
## Step 7: Report
Output a clear diagnosis:
```
Run #257649 — "Welcome Email" (form-level, Submission Created)
Status: FAILED
Timeline:
1. ✓ Start (system_start_v1) — 0ms
2. ✓ Build Email (utilities_echo_v1) — 2ms
3. ✗ Send Email (smtp_email_send_v1) — FAILED
Error: Connection refused to SMTP server
Root Cause: SMTP server is unreachable
Fix: Check SMTP handler source configuration — verify host/port/credentials
```
Suggest specific fixes based on the diagnosis.