Debugging Workflows
Watch your workflow run, pause where it matters, and inspect the data flowing between steps.
Circuitry debugging works on two levels: watch the whole workflow execute live, and set breakpoints inside code to step through line by line.
See execution live
When a workflow runs, follow it on the canvas — each node shows its status (running, complete, error) and you can inspect the output of any node as data moves through. This makes it easy to spot where a pipeline goes wrong.
Run Log
Open it from Menu → Debug → Show Run Log (or the Run Log toggle in the top toolbar). It's a chronological, call-stack-ordered trace of every node that ran — timing, model, server, outcome, and (on click) the node's output. Agent tool calls (MCP servers, vector stores, procedures) are indented under the agent that made them, so you can see exactly what was called and in what order.
Breakpoints on nodes
Right-click a node and choose Enable Breakpoint. A red dot appears just outside the node's top-left corner, and every run stops before that node, with the input it is about to get shown in the Debugger panel. While the run waits there, the dot turns yellow and the board moves to that node. Then:
- Press the round Run this node button centred just above it: the node runs and the run stops again at the next node, so you can look at what it produced before anything else runs. The node's own Run button does the same.
- Or use the run controls at the top of the board: Resume runs on to the next breakpoint, Step runs this node and stops at the next, and Stop ends the run.
Pause stops a run before its next node in the same way. Click a red dot, or choose Remove Breakpoint, to clear it. Breakpoints are saved with the workflow.
Breakpoint debugging for code
Inside Code nodes and code documents, set breakpoints to pause execution for Python, JavaScript and TypeScript:
- Step over, into, and out of lines.
- Inspect variables and their values while paused.
- Resume when you're ready.
This runs on your own device — no server required.
Set one by clicking the margin to the left of the line number, or by pressing F9 with the cursor on the line. By touch, press and hold the line and choose Breakpoint from the bar that appears — it reads Clear breakpoint when there is already one there.
Only the languages above offer any of this: on the others there is no margin to click and no Breakpoint in the bar, because there is nothing that could stop there.
In a code document
A code document — the file you get from + → Code, with no workflow around it — debugs on its own. Its status bar has Debugging beside Run. The bug is a switch: it is dim until you add a breakpoint, and adding one lights it. While it is lit, Run stops at your breakpoints; tap it to turn debugging off and run straight through, and tap again to turn it back on.
While the file is being debugged, a debug bar is docked above the code with Stop, Continue, Over, Into, Out and the line it stopped on. The Debug tab in the sidebar lists your breakpoints and shows the variables in scope while paused.
The bug only appears for a language that can actually stop.
A Python file that draws in its preview (Pyctures) stops at breakpoints when it runs on iPhone or iPad, with Circuitry's built-in Python; elsewhere it runs straight through and says so. See Debugging Python graphics.
A TypeScript file or step pauses on the lines you wrote: its types are blanked out where they stand rather than deleted, so nothing shifts up and a breakpoint beside line 15 stops on line 15.
Lua, Go, Rust, C, C++ and Zig don't have breakpoints. Print instead — print in Lua, fmt.Println in Go, println! in Rust, printf in C and C++, std.debug.print in Zig — and the output appears in the output panel alongside everything else.
Debugging a web page
A script that draws on a canvas or reads the document can't run on its own — it asks for a page on its first line. Set a breakpoint in it and Circuitry finds the page that loads it and stops there instead, with the same controls and the same Variables list.
Run from a point
Re-run just part of a workflow: run a single node on its own, or run from a chosen node onward, so you don't repeat expensive earlier steps while iterating.
Tips
- Inspect a node's output before assuming the next node is at fault — most bugs are upstream.
- Use breakpoints to check a value mid-computation rather than adding print statements.
- Re-run from the failing node to iterate quickly.