Debug

Learn how to debug your workflows and troubleshoot issues

Overview

Jinba Flow provides several debugging features to help you identify and fix issues in your workflows. You can run individual steps, view execution history, inspect step outputs, and analyze errors to quickly resolve problems.

Debugging Features

Single Step Execution

Test individual steps in isolation to verify they work correctly:

• Isolated Testing: Run a single step without executing the entire workflow
• Previous Outputs: Use outputs from previous workflow runs as input
• Quick Validation: Verify step configuration and logic before full execution
• Error Isolation: Identify which specific step is causing issues

Flow Run History

View and analyze past workflow executions:

• Execution Logs: See detailed logs of all workflow runs
• Step Status: Check which steps succeeded, failed, or were skipped
• Timing Information: View execution time for each step
• Output Inspection: Examine outputs from each step

Error Messages

Comprehensive error reporting helps identify issues:

• Step-Level Errors: See exactly which step failed and why
• Error Details: View error messages, stack traces, and context
• Validation Errors: Get clear messages about configuration issues

Running a Single Step

Step 1: Open Your Workflow

1. Open your workflow in the Flow Editor
2. Navigate to the step you want to debug
3. Ensure the step is properly configured

Step 2: Run Single Step

1. Click on the step you want to test
2. Look for the Run Step or Test Step option
3. If previous outputs are available, they will be used as input
4. Click to execute the step

Step 3: Review Results

1. Check the step output in the step panel
2. Verify the output matches your expectations
3. If there are errors, review the error message
4. Make adjustments and test again

Note: Single step execution uses outputs from your most recent workflow run. If no previous run exists, the step will run with empty or default inputs.

Using Previous Outputs

When debugging a step, you can use outputs from previous workflow executions:

1. Automatic Detection: The system automatically detects available previous outputs
2. Output Selection: Previous step outputs are used as inputs for the step being tested
3. Manual Override: You can manually specify inputs if needed

This allows you to test steps in the context of actual workflow data without running the entire workflow.

Viewing Flow Run History

Accessing Run History

1. Open your workflow in the Flow Editor
2. Navigate to the Runs or History tab
3. View a list of all workflow executions

Analyzing Run Results

Each run shows:

• Status: Success, failure, or in progress
• Execution Time: How long the workflow took to complete
• Step Status: Individual status for each step
• Outputs: Final workflow output
• Errors: Any errors that occurred during execution

Inspecting Step Outputs

1. Click on a specific run in the history
2. Expand individual steps to see their outputs
3. Review input and output data for each step
4. Identify where issues occurred

Understanding Error Messages

Common Error Types

Validation Errors

These occur when step configuration is incorrect:

• Missing Required Fields: Required inputs or configs are not provided
• Invalid Values: Input values don’t match expected types or formats
• Missing Dependencies: Referenced steps or secrets don’t exist

Example: “Missing required input: ‘api_key‘“

Execution Errors

These occur during step execution:

• API Errors: External service returned an error
• Timeout Errors: Step execution exceeded time limit
• Permission Errors: Insufficient permissions for the operation

Example: “API request failed: 401 Unauthorized”

Dependency Errors

These occur when step dependencies aren’t met:

• Missing Previous Outputs: Required previous step outputs are not available
• Circular Dependencies: Steps have circular dependency chains
• Invalid References: Referenced step IDs don’t exist

Example: “Step ‘step_2’ depends on ‘step_1’ which was not executed”

Reading Error Messages

Error messages typically include:

1. Error Type: What kind of error occurred
2. Step ID: Which step failed
3. Error Message: Human-readable description
4. Stack Trace: Technical details for debugging (if available)
5. Context: Additional information about the error

Debugging Workflow

Step-by-Step Debugging Process

1. Identify the Problem: Review error messages and failed steps
2. Isolate the Issue: Use single step execution to test individual steps
3. Check Inputs: Verify that step inputs are correct
4. Review Configuration: Ensure step configs (API keys, settings) are valid
5. Test Fixes: Make changes and test again with single step execution
6. Run Full Workflow: Once individual steps work, run the full workflow

Common Debugging Scenarios

Scenario 1: Step Fails Immediately

Problem: A step fails as soon as it starts executing.

Debugging Steps:

1. Check step configuration (API keys, settings)
2. Verify input values are correct
3. Test the step in isolation using single step execution
4. Review error message for specific issues

Scenario 2: Step Produces Unexpected Output

Problem: Step executes successfully but output is incorrect.

Debugging Steps:

1. Review step inputs to ensure they’re correct
2. Check step logic and tool configuration
3. Test with different input values
4. Compare with expected output format

Scenario 3: Workflow Fails Mid-Execution

Problem: Workflow starts successfully but fails partway through.

Debugging Steps:

1. Identify which step failed from run history
2. Check if previous steps produced correct outputs
3. Verify step dependencies are correct
4. Test the failing step in isolation

Scenario 4: Conditional Logic Issues

Problem: Steps with when conditions aren’t executing as expected.

Debugging Steps:

1. Verify condition expressions are correct
2. Check that referenced step outputs exist
3. Test condition evaluation with actual data
4. Review step execution order

Best Practices

1. Test Incrementally: Build and test workflows step by step
2. Use Single Step Execution: Test individual steps before running full workflow
3. Review Run History: Regularly check execution history for patterns
4. Validate Inputs: Ensure inputs are correct before execution
5. Check Error Messages: Read error messages carefully for specific guidance
6. Test with Real Data: Use actual data when possible for more accurate testing
7. Document Expected Behavior: Note expected outputs for easier debugging

Troubleshooting Tips

Step Not Executing

• Check Dependencies: Ensure all required previous steps completed successfully
• Verify Conditions: If step has when condition, ensure condition is met
• Review Execution Order: Check that steps are ordered correctly

Unexpected Outputs

• Inspect Inputs: Verify inputs to the step are what you expect
• Check Tool Configuration: Ensure tool settings are correct
• Review Tool Documentation: Confirm you’re using the tool correctly

Performance Issues

• Check Execution Time: Review step execution times in run history
• Identify Slow Steps: Find steps that take longest to execute
• Optimize Configuration: Adjust settings to improve performance

API Errors

• Verify Credentials: Check that API keys and credentials are valid
• Review Rate Limits: Ensure you’re not exceeding API rate limits
• Check Service Status: Verify external services are operational

Related Features

• Publish - Learn about publishing workflows
• Workspace - Learn about workspace management
• Credit Costs - Understand workflow execution costs