Flows

Debugging flows

Debug Flows using execution logs, step-by-step inspection, and testing tools to identify and fix issues.

Test execution

The fastest way to debug is running the Flow with test inputs:

  1. Open the Flow in the editor
  2. Click Run to open the Run Flow panel
  3. Provide test input
  4. Click Run Flow. To capture full step-by-step traces, open the mode selector and choose Run in debug mode before running.
  5. Review results in the execution panel
  6. Happy with the output? Click Save as test case to capture this run’s input and expected answer as a persisted test case in the Flow’s eval suite (created automatically the first time you use it). See Managing eval suites.

The panel shows each step’s input, output, and execution time.

Execution logs

View detailed logs for all Flow executions:

  1. Click Logs in the sidebar
  2. Filter by Flow name
  3. Click an execution to see details

Logs include:

  • Full execution trace
  • Step inputs and outputs
  • Error messages and stack traces
  • Timing information
  • Variable values at each step

See Working with Logs for more details.

Step-by-step inspection

In the test execution panel, click any step to see:

  • Input: Data passed to the step
  • Output: Data returned by the step
  • Duration: How long the step took
  • Status: Success or error

This helps identify which step is failing or producing unexpected output.

Common errors

Undefined variable

Error: Cannot read property 'output' of undefined

Cause: Referencing a step that hasn’t executed yet or doesn’t exist.

Fix: Check step name spelling and execution order.

API call failure

Error: Request failed with status 401

Cause: API authentication issues or invalid endpoint.

Fix: Verify API keys, check headers, test endpoint externally.

Timeout

Error: Step execution timed out

Cause: Step took too long (default 5-minute step timeout, 15-minute Flow timeout).

Fix: Optimize slow operations or adjust the step timeout.

Invalid JSON

Error: Unexpected token in JSON

Cause: Malformed JSON in request body or transform step.

Fix: Validate JSON syntax, check for unquoted strings or trailing commas.

Debugging techniques

Add inspection steps

Insert transform-data steps to inspect variable values. Flow variables are available by their outputVariable name:

1return {
2  logged: true,
3  customer_data_value: customer_data,
4  total_value: calculate_total
5};

Check the step output in the execution results to see the returned values.

Test incrementally

Build Flows step by step, testing after each addition:

  1. Add first step, test
  2. Add second step, test
  3. Continue until you identify where it breaks

Simplify complex steps

If a step has complex logic, break it into smaller steps:

Instead of one transform step doing everything, use:

  1. Transform: Extract data
  2. Transform: Format data
  3. Transform: Calculate final value

This makes it easier to see where logic fails.

Use default values

Add fallbacks to prevent null reference errors:

{{customer_data.tier || "standard"}}
{{order_history.count || 0}}

Run Flows with edge cases: empty inputs, null values, large datasets, invalid data. This reveals issues that normal testing might miss.

Debugging conditionals

Test both branches:

  1. Run with input that makes condition true
  2. Verify “if” branch executes
  3. Run with input that makes condition false
  4. Verify “else” branch executes

Check that variables referenced in conditions exist and have expected types.

Performance debugging

If Flows are slow:

  1. Check step durations in execution logs
  2. Identify the slowest step
  3. Optimize:
    • Use faster AI models for simple tasks
    • Reduce prompt length
    • Simplify transform-data steps
    • Remove unnecessary steps

Validation errors

Add validation steps at the beginning of Flows using a transform-data step:

1if (!customerId) {
2  throw new Error('Customer ID is required');
3}
4
5return { validated: true };

Next steps