Workflow Debugging and Monitoring
Use the validation checklist, debug runs, node traces, and run metrics to locate issues
Workflow issues fall into configuration issues, data flow issues, and runtime issues. Work through the checklist first, then a debug run, then node traces and run metrics.
Configuration Validation
The Checklist reports each of these before publishing: unselected models, tools, or knowledge bases; inputs/outputs without a source; nonexistent variable references; incomplete conditional branches; a Decision node missing its model, state, or instructions, with an invalid number or uniqueness of options/levels, or with connections pointing at an outdated decision branch handle; empty code or templates; iterations/loops missing their start or processing nodes; and no output node.
The checklist only covers structural problems — it cannot tell you whether a branch is actually reachable. That is what a debug run answers.
Debug Runs
Select Debug Run and fill in the inputs. It calls POST /api/v1/workflows/{workflow_id}/debug, which needs the workflow:run permission plus write access to the workflow, creates a run with is_debug: true, and immediately returns a run_id and stream_url; the actual execution happens in a background task.
A debug run uses the current draft and never modifies the published version; a production run loads the latest published version's snapshot instead. Publishing is the only thing that moves draft edits onto the production path.
When the debug run finishes, the run drawer's Details shows inputs, outputs, and errors; Trace shows each node's status, inputs, outputs, Tokens, duration, and retry count. Connecting to GET /api/v1/workflows/runs/{run_id}/stream delivers node events and LLM streaming output in real time.
Debug runs backfill variable types
After every debug run, the backend infers a type for each output from the node execution records and union-merges it into the draft definition's existing data.inferredSchema:
- The editor refetches the workflow when the debug run completes, so the variable picker offers field-level completion after a single trial run instead of forcing you to declare shapes by hand.
- Internal outputs whose names start with
_(such as_iteration_state,_loop_complete) are skipped and never enter the inferred schema. - Only debug runs write inference back; production runs deliberately skip it so live traffic shapes cannot drift the editor's type hints.
There are no breakpoints or single-step debugging. The codebase contains internal debug-session and breakpoint definitions, but no API route or UI exposes them, so debugging is always a whole run plus post-mortem tracing. To narrow things down, split large logic into several nodes, or temporarily add a Variable Assignment or Answer node to surface an intermediate value.
Run Status
Run-level statuses:
| Status | Meaning |
|---|---|
pending | Created, waiting for execution |
running | Executing |
waiting | Stopped at a Pause node, waiting for an approval decision or extra variables |
success | All flows completed successfully |
failed | A node or the runtime failed |
cancelled | Cancelled by the user |
timeout | Reached the runtime limit |
Node-level statuses add skipped: the node was skipped by a condition branch or a loop. Skipped is not a failure and never appears as a run-level status.
Monitoring Metrics
The workflow Monitoring page (/app/apps/workflow/{id}/monitor) is powered by two endpoints:
| Endpoint | Contents |
|---|---|
GET /api/v1/workflows/{id}/stats | Total runs, success count, failure count, timeout count, average duration, and last run time; not time-bounded, covering the workflow's whole history |
GET /api/v1/workflows/{id}/stats/trends?period=7d|30d | Daily run, success, failure, and average-duration buckets on local-day boundaries; period only recognises 30d, anything else is treated as 7d |
The Monitoring page switches between 7d and 30d, shows cards for total runs, success rate, average duration, and failures, then a trend chart and recent runs. Run logs support filtering by status, time, and full run ID.
Team- and system-level run statistics are available at GET /api/v1/workflows/runs/stats; admin-level aggregated metrics (dashboard summary, per-workflow metrics, node-type metrics, running workflows, cache stats and clearing) live under /api/v1/admin/workflows/metrics/* and require administrator permissions.
Troubleshooting Order
- Check whether the input variables exist and have the correct types.
- Look at the first failed node, not just the final error.
- For LLMs, check model authorization, prompt, and Tokens; for HTTP, check the URL, headers, timeout, and response path; for code, check package versions, resource limits, and artifact paths.
- For a Decision node, check that the model is of type decision and authorized for the team, then read
selected_handle,confidence, andprobabilitiesin the trace to tell a threshold problem from an instructions problem (see Orchestrate a Workflow → Decision Node). - For knowledge bases, check whether documents finished processing, whether embedding dimensions match, and whether the retrieval service is available.
- If it is a published app, confirm the failure happened on the published version rather than in the draft editor.
How is this guide?