Debugging Pipelines

Use breakpoints, step through execution, and inspect variables in your FlowMason pipelines.

FlowMason provides full debugging support through VSCode’s Debug Adapter Protocol with WebSocket-powered real-time communication, giving you the same debugging experience you’d expect from traditional code—plus powerful AI-specific features like prompt iteration.

Setting Breakpoints

In the Editor

Click in the gutter (left margin) next to any stage in your pipeline to set a breakpoint.

Keyboard Shortcut

Press F9 with your cursor on a stage line.

In the DAG Editor

Right-click on any stage node and select “Toggle Breakpoint”.

Starting a Debug Session

1. Open a .pipeline.json file
2. Press F5 or click “Start Debugging”
3. Provide input when prompted

The pipeline will execute until it hits a breakpoint.

Debug Controls

Inspecting Variables

When paused at a breakpoint, the Variables panel shows:

Input

The current stage’s input data.

Output

The stage’s output (after execution).

Context

Pipeline context including:

• Pipeline metadata
• Execution ID
• LLM provider info

Previous Stages

Output from all completed stages.

Watch Expressions

Add expressions to monitor specific values:

stages.fetch.output.status
input.url.length
stages.extract.output.items[0]

Prompt Iteration

For AI nodes, FlowMason’s Prompt Iteration feature lets you refine prompts without restarting your pipeline:

Prompt Editor Panel

1. View the fully rendered prompt with all variables resolved
2. Edit the prompt directly in the editor
3. Re-run the stage with your changes instantly
4. Compare before/after results side-by-side

Iteration Workflow

1. Pause at AI node breakpoint
2. View rendered prompt in Prompt Editor
3. Modify prompt text
4. Click "Re-run Stage"
5. Compare output to previous
6. Repeat until satisfied
7. Continue execution

Saving Iterations

When you find an improvement, the Prompt Editor can update your source file:

• Click “Apply to Source” to update the component
• Changes are saved with Git-friendly formatting
• Original prompt preserved in version control

This is invaluable for iterating on prompts without restarting your pipeline.

Conditional Breakpoints

Right-click on a breakpoint to add a condition:

stages.fetch.output.status === 404
input.items.length > 10

The breakpoint only triggers when the condition is true.

Exception Breakpoints

Configure when to pause on errors:

• All Errors - Pause on any error
• Uncaught Errors - Only pause on unhandled errors
• Timeouts - Pause when a stage times out
• Validation Errors - Pause on schema validation failures

Debug Console

Evaluate expressions while paused:

> stages.extract.output
{ "text": "...", "metadata": {...} }

> input.url.split('/').pop()
"article-123"

Tips

1. Use logging stages - Add logger operators to track values
2. Start simple - Debug with minimal input first
3. Check dependencies - Verify stage outputs match expected inputs
4. Use conditional breakpoints - Skip to interesting cases
5. Iterate on prompts - Use the Prompt Editor to refine AI behavior