Debugging

Because Ironflow records every step as a permanent fact, debugging is built into the foundation — not bolted on. Ironflow provides history correction (hot patching) for recovery, history navigation (time-travel debugging) via TUI and dashboard, VS Code integration via DAP, and a request inspector.

---

Inspecting Runs via CLI

The ironflow run subcommands cover the most common run inspection flows:

• ironflow run list — list recent runs
• ironflow run get <run_id> — view run details
• ironflow run pause <run_id> — pause for inspection/injection
• ironflow run resume <run_id> — resume a paused run
• ironflow run cancel <run_id> — cancel
• ironflow run inject <run_id> <step_id> --output <json> — inject step output (see scoped-injection guide)
• ironflow run paused-state <run_id> — get paused snapshot

---

History Correction — Hot Patching (Recovery from Failures)

When a step fails, you can edit its output and resume the workflow without re-running expensive operations.

Via Dashboard

1. Navigate to Runs and click a failed run
2. Find the failed step in the timeline
3. Click Edit to modify the step output
4. Enter the corrected JSON output and a reason
5. Click Save Patch then Resume Run

Via API

Patch a step output:

curl -X POST http://localhost:9123/api/v1/steps/patch \
  -H "Content-Type: application/json" \
  -d '{
    "step_id": "step_abc123",
    "output": {"corrected": "value"},
    "reason": "Fixed invalid response from external API"
  }'

Resume a paused/failed run:

curl -X POST http://localhost:9123/api/v1/runs/resume \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "run_xyz789",
    "from_step": "step_abc123"
  }'

The workflow resumes from the specified step (or the failed step if not specified), using the patched output.

Tip: Hot patching fixes failures after they happen. For live intervention on running workflows, see Scoped Injection — pause at step boundaries, inspect outputs, inject modifications, and resume.

---

TUI Debugger

Inspect completed or failed workflow runs with a terminal-based interface:

./build/ironflow inspect <run_id>

Features:

• Step-by-step navigation through workflow execution
• View step inputs, outputs, and metadata
• Set breakpoints on specific steps
• Jump to first/last step
• View patched vs original outputs

Keyboard shortcuts:

Key	Action
j/k or ↑/↓	Navigate steps
n/p	Next/previous step
g/G	Jump to first/last
Tab, h, or l	Switch panels
b	Toggle breakpoint
c	Continue to breakpoint
q	Quit

---

VS Code Debugging (DAP)

Start a Debug Adapter Protocol server for VS Code integration:

./build/ironflow inspect <run_id> --dap --dap-port 4711

Add to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "ironflow",
      "request": "attach",
      "name": "Ironflow Inspect",
      "port": 4711
    }
  ]
}

DAP Features:

• Step through workflow execution in VS Code
• View step inputs/outputs as variables
• Set breakpoints by step number
• Standard debugging controls (Continue, Step Over, etc.)

Concept mapping:

Workflow	Debugger
Run	Debug Session
Step	Stack Frame
Step sequence	Line number
Step input/output	Variables
Step name	Frame name

---

Request Inspector

The dashboard includes a request inspector for debugging API interactions:

1. Navigate to Inspector in the sidebar
2. View recent HTTP requests with method, path, status, and duration
3. Expand any request to see headers, request body, and response body
4. Enable auto-refresh to see requests in real-time
5. Clear history when needed

API access:

# Get recent requests
curl http://localhost:9123/api/v1/debug/requests

# Clear request history
curl -X DELETE http://localhost:9123/api/v1/debug/requests

---

Debugging Tips

1. Check the Dashboard

The dashboard at http://localhost:9123 shows:

• Recent runs and their status
• Step-by-step execution details
• Input and output data for each step
• Error messages for failed steps

2. Use the TUI for Terminal Workflows

When working in the terminal, the TUI debugger provides a fast way to inspect runs without opening a browser:

# List recent runs via REST API
curl http://localhost:9123/api/v1/runs

# Inspect a specific run
./build/ironflow inspect run_abc123

3. Enable Verbose Logging

For detailed execution logs:

LOG_LEVEL=debug ./build/ironflow serve

Start the server with --pprof to enable Go pprof endpoints on 127.0.0.1:6060 for runtime profiling.

4. Test Functions in Isolation

Before integrating, exercise your function logic with the test client:

import { createTestClient } from "@ironflow/node/test";
import { ironflow } from "@ironflow/node";

const myFunction = ironflow.createFunction(
  { id: "process-order", triggers: [{ event: "order.created" }] },
  async ({ event, step }) => {
    const result = await step.run("validate", async () => ({
      orderId: event.data.orderId,
    }));
    return { validated: result };
  },
);

const test = createTestClient({ functions: [myFunction] });
test.mockStep("validate", () => ({ orderId: "test_123" }));

const run = await test.emit("order.created", { orderId: "test_123" });
console.log(run.status); // "completed" | "failed"
console.log(run.output); // { validated: { orderId: "test_123" } }

See Testing Workflows for full coverage.

---

What’s Next?

• API Reference — REST API endpoints