> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug Tools

> Diagnose and resolve agent execution errors using built-in debugging tools, error handling configurations, and test environments

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](/02-building-agents/agent-configuration/flow-builder/flow-builder).

<Steps>
  <Step title="Select Node to Test">
    Open Flow builder and click the node experiencing issues or requiring validation.
  </Step>

  <Step title="Access Test Tool">
    In node configuration panel, locate "Test" or "Run Test" option to open test interface.
  </Step>

  <Step title="Provide Mock Input">
    Enter sample input data matching expected node input schema. Use real examples from failed tasks (see [Task Executions](/03-running-operations/task-management/task-executions/task-executions)) or create test cases in [Test Datasets](/03-running-operations/debugging-testing/test-datasets/test-datasets).
  </Step>

  <Step title="Execute Test">
    Run node test. System executes only this node with provided input, bypassing earlier workflow steps.
  </Step>

  <Step title="Inspect Output">
    Review node output, validation results, and any error messages. Compare against expected behavior defined in [Evaluation Framework](/04-observability-analytics/evaluation-framework/evaluation-framework).
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="When to Use Test Tool">
    **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
  </Accordion>

  <Accordion title="Test Tool Best Practices">
    **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
  </Accordion>
</AccordionGroup>

## 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

<AccordionGroup>
  <Accordion title="Configuring Continue on Error">
    **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
  </Accordion>

  <Accordion title="Handling Missing Data">
    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
  </Accordion>
</AccordionGroup>

### 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

<AccordionGroup>
  <Accordion title="Retry Best Practices">
    **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
  </Accordion>
</AccordionGroup>

## 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](/03-running-operations/task-management/task-executions/task-executions) for comprehensive monitoring guidance.

<Steps>
  <Step title="Navigate to Task">
    Go to Tasks page and select failed or problematic task execution.
  </Step>

  <Step title="View Execution Timeline">
    See complete workflow execution with each node's status, duration, and output.
  </Step>

  <Step title="Inspect Failed Step">
    Click failed node to view error message, input data received, and attempted output.
  </Step>

  <Step title="Review Error Details">
    Examine error type, stack trace (for integration errors), and contextual information.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Common Error Patterns">
    **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, re-authenticate 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
  </Accordion>

  <Accordion title="Debugging Workflow">
    **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:**
       * Rerun original failed task (see [Rerunning Tasks](/03-running-operations/debugging-testing/rerunning-tasks/rerunning-tasks))
       * Run test dataset with similar cases (see [Test Datasets](/03-running-operations/debugging-testing/test-datasets/test-datasets))
       * Monitor for recurrence in [Task Executions](/03-running-operations/task-management/task-executions/task-executions)
  </Accordion>
</AccordionGroup>

## 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](/02-building-agents/agent-configuration/agent-settings/agent-settings))
2. Select "Learning" or "Observability" section
3. View LangFuse dashboard for agent executions
4. Filter by timeframe, status, or specific runs

<AccordionGroup>
  <Accordion title="Using LangFuse for Debugging">
    **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
  </Accordion>

  <Accordion title="LangFuse Best Practices">
    **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
  </Accordion>
</AccordionGroup>

## 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](/02-building-agents/agent-configuration/agent-settings/agent-settings))
* **Production Environment**: Live agent processing real tasks

<AccordionGroup>
  <Accordion title="Using Sandbox Effectively">
    **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
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Debug Systematically">
    **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
  </Accordion>

  <Accordion title="Leverage Error Handling Strategically">
    **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
  </Accordion>

  <Accordion title="Monitor and Improve">
    **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
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Rerunning Tasks" icon="rotate" href="/03-running-operations/debugging-testing/rerunning-tasks/rerunning-tasks">
    Rerun failed tasks after applying debugging fixes
  </Card>

  <Card title="Test Datasets" icon="vial" href="/03-running-operations/debugging-testing/test-datasets/test-datasets">
    Create test datasets to validate debugging improvements
  </Card>

  <Card title="Optimize Outputs" icon="sparkles" href="/04-observability-analytics/optimize-outputs/optimize-outputs">
    Use AI-powered optimization to improve failing prompts
  </Card>

  <Card title="Task Executions" icon="chart-line" href="/03-running-operations/task-management/task-executions/task-executions">
    Monitor task execution results to identify issues
  </Card>
</CardGroup>