Skip to main content
Debug tools help identify and resolve issues in agent workflows through systematic error analysis, node-level testing, and execution tracing.

​
Understanding Debug Tools

Beam provides multiple debugging approaches for different scenarios: Test Tool - Isolate and test individual nodes with mock input data to debug specific workflow steps Error Handling - Configure how agents respond to failures, including continue-on-error and retry logic Execution Logs - Detailed step-by-step traces showing inputs, outputs, and errors for each node LangFuse Integration - Advanced observability platform for tracing agent behavior and identifying issues

​
Test Tool for Node Debugging

Test individual workflow nodes in isolation without running the entire agent workflow. Configure nodes in Flow Builder.
1

Select Node to Test

Open Flow builder and click the node experiencing issues or requiring validation.
2

Access Test Tool

In node configuration panel, locate “Test” or “Run Test” option to open test interface.
3

Provide Mock Input

Enter sample input data matching expected node input schema. Use real examples from failed tasks (see Task Executions) or create test cases in Test Datasets.
4

Execute Test

Run node test. System executes only this node with provided input, bypassing earlier workflow steps.
5

Inspect Output

Review node output, validation results, and any error messages. Compare against expected behavior defined in Evaluation Framework.
Node Producing Unexpected Output:
  • Data extraction returning wrong values
  • Classification categorizing incorrectly
  • Integration call failing
  • Field mapping errors
Validating Prompt Changes:
  • Test new prompts before full workflow run
  • Compare outputs with different prompt versions
  • Verify edge case handling
Debugging Integration Nodes:
  • Test API authentication
  • Validate request/response format
  • Check integration configuration
  • Verify data transformation logic
Use Real Production Data:
  • Test with actual failed task inputs
  • Include edge cases from production
  • Cover variety of input formats
Iterative Testing:
  • Test → Adjust → Test cycle
  • Small changes between iterations
  • Document what works
Compare Before/After:
  • Test with old configuration
  • Make single change
  • Test with new configuration
  • Measure improvement
Build Test Case Library:
  • Save successful test inputs
  • Reuse for regression testing
  • Share with team for consistency

​
Error Handling Configuration

Configure how agents respond to errors at workflow and node levels.

​
Continue on Error

Allow workflow to proceed even when specific nodes fail. Node-Level Setting:
  • Enable “Continue on error” in node configuration
  • Workflow proceeds to next step even if this node fails
  • Failed node output marked as error, available to downstream nodes
  • Useful for non-critical steps where failure shouldn’t block entire workflow
Use Cases:
  • Optional data enrichment that shouldn’t block processing
  • Logging or notification steps
  • Non-essential validation checks
  • Backup or fallback operations
When to Enable:
  • Step is optional for workflow completion
  • Downstream nodes handle missing data gracefully
  • Failure rate is acceptable (e.g., external API occasionally unavailable)
  • Manual review will catch issues later
When NOT to Enable:
  • Critical data extraction or validation
  • Security or compliance checks
  • Payment or transaction processing
  • Data accuracy is paramount
Implementation:
  1. Open node configuration in Flow builder
  2. Locate “Error Handling” section
  3. Toggle “Continue on error” option
  4. Test with failing scenarios to verify behavior
  5. Publish workflow changes
When upstream node fails with “Continue on error” enabled:Downstream Node Strategy:
  • Check if required input exists before processing
  • Use conditional branches to route around missing data
  • Provide default values for missing fields
  • Flag task for human review when critical data missing
Example Workflow:
  • Node 1: Extract invoice data (Continue on error: enabled)
  • Node 2: Check if invoice_amount exists
  • Branch A: Amount exists → Process payment
  • Branch B: Amount missing → Route to inbox for manual review

​
Auto-Retry on Error

Automatically retry failed steps to handle transient errors. Retry Configuration:
  • Set maximum retry attempts (typically 1-3)
  • Configure retry delay between attempts
  • Specify error types that trigger retry vs immediate failure
Common Retry Scenarios:
  • API timeout errors (network issues)
  • Rate limiting (429 errors)
  • Temporary service unavailability (503 errors)
  • Database connection failures
Appropriate for Retries:
  • Network timeouts
  • Temporary service outages
  • Rate limiting
  • Resource temporarily unavailable
NOT Appropriate for Retries:
  • Authentication errors (won’t resolve with retry)
  • Invalid request format (will fail again)
  • Missing required data
  • Business logic errors
Retry Strategy:
  • Start with 2 retries maximum
  • Use exponential backoff for delays
  • Monitor retry frequency
  • High retry rates indicate underlying issue needing fix

​
Execution Logs and Tracing

Analyze detailed execution logs to identify root causes of failures.

​
Accessing Execution Logs

View step-by-step execution details for any task. See Task Executions for comprehensive monitoring guidance.
1

Navigate to Task

Go to Tasks page and select failed or problematic task execution.
2

View Execution Timeline

See complete workflow execution with each node’s status, duration, and output.
3

Inspect Failed Step

Click failed node to view error message, input data received, and attempted output.
4

Review Error Details

Examine error type, stack trace (for integration errors), and contextual information.
Data Format Errors:
  • Symptom: Node expecting JSON receives text
  • Solution: Check upstream node output format, update extraction prompt
Missing Required Fields:
  • Symptom: Node fails with “field X is required”
  • Solution: Verify upstream extraction captured all fields, check input data completeness
Integration Authentication Errors:
  • Symptom: 401 Unauthorized from API calls
  • Solution: Verify integration credentials in Integrations page, refresh tokens if expired
Timeout Errors:
  • Symptom: Node exceeds execution time limit
  • Solution: Optimize prompt complexity, reduce input size, or enable auto-retry
Context Window Exceeded:
  • Symptom: Silent failure or truncation errors
  • Solution: Reduce input size, summarize before processing, or split into smaller chunks
Systematic Debugging Approach:
  1. Reproduce Error:
    • Identify exact input causing failure
    • Rerun task to confirm error persists
    • Note if error is consistent or intermittent
  2. Isolate Failed Step:
    • Identify which node failed
    • Review input that node received
    • Check if input matches expected format
  3. Test in Isolation:
    • Use Test Tool with same input
    • Verify error reproduces
    • Try variations to find working input
  4. Identify Root Cause:
    • Prompt issue (unclear instructions)
    • Integration issue (API error, auth failure)
    • Data issue (malformed input, missing fields)
    • Configuration issue (wrong tool selected, invalid parameters)
  5. Apply Fix:
    • Update prompt, configuration, or integration
    • Test fix with same input
    • Verify resolution
  6. Validate:

​
Advanced Debugging with LangFuse

Integrated observability platform for deep execution tracing and performance analysis. LangFuse Capabilities:
  • Complete execution traces across all nodes
  • Token usage and cost tracking
  • Latency analysis per step
  • Model behavior insights
  • Error pattern identification
Accessing LangFuse:
  1. Navigate to agent configuration (see Agent Settings)
  2. Select “Learning” or “Observability” section
  3. View LangFuse dashboard for agent executions
  4. Filter by timeframe, status, or specific runs
Performance Debugging:
  • Identify slow nodes causing delays
  • Analyze token usage for cost optimization
  • Compare execution times across test runs
Behavior Analysis:
  • Review exact prompts sent to model
  • See model responses and reasoning
  • Identify prompt inconsistencies
  • Track how model handles edge cases
Error Investigation:
  • Trace error through full execution chain
  • See context available at failure point
  • Identify data quality issues
  • Verify integration call details
Regular Monitoring:
  • Review LangFuse traces for critical agents weekly
  • Check for anomalies in execution patterns
  • Monitor cost trends
Failure Analysis:
  • Always check LangFuse for persistent failures
  • Compare successful vs failed execution traces
  • Look for subtle input differences causing issues
Performance Optimization:
  • Identify nodes with excessive token usage
  • Find opportunities to reduce latency
  • Optimize prompt efficiency

​
Sandbox and Testing Environments

Isolated testing environments for safe experimentation without affecting production. Sandbox Benefits:
  • Test integration changes safely
  • Validate workflow modifications
  • Experiment with prompts
  • Train team members
  • Demo features to stakeholders
E2E vs Production:
  • E2E Environment: Full workflow testing with test data before production deployment (configure in Agent Settings)
  • Production Environment: Live agent processing real tasks
Pre-Deployment Testing:
  1. Make changes in E2E environment
  2. Run test datasets to validate
  3. Review execution logs for errors
  4. Compare metrics to production baseline
  5. Deploy to production if tests pass
Integration Testing:
  • Set up test API credentials for sandbox
  • Use test accounts for external services
  • Validate end-to-end data flow
  • Check error handling with simulated failures
Training and Demos:
  • Safe environment for team training
  • Demo new features to stakeholders
  • Experiment with new capabilities
  • No risk to production data

​
Best Practices

Start Simple:
  • Test individual nodes before full workflow
  • Use Test Tool to isolate issues
  • Verify one change at a time
Document Findings:
  • Record what worked and what didn’t
  • Note error messages and resolutions
  • Build knowledge base for team
Test Thoroughly:
  • Use diverse test cases
  • Include edge cases
  • Validate with production-like data
Continue on Error:
  • Only for truly optional steps
  • Ensure downstream handles missing data
  • Monitor failure rates
Auto-Retry:
  • For transient errors only
  • Limit retry attempts to 2-3
  • Track retry frequency to spot systematic issues
Regular Reviews:
  • Check execution logs weekly
  • Review LangFuse traces for patterns
  • Identify recurring error types
Proactive Optimization:
  • Fix high-frequency errors
  • Optimize slow nodes
  • Update prompts based on failures
  • Improve error handling coverage
Build Resilience:
  • Add error handling to critical paths
  • Create fallback workflows
  • Implement human review for edge cases
  • Test disaster recovery scenarios

​
Next Steps

Rerunning Tasks

Rerun failed tasks after applying debugging fixes

Test Datasets

Create test datasets to validate debugging improvements

Optimize Outputs

Use AI-powered optimization to improve failing prompts

Task Executions

Monitor task execution results to identify issues