> ## 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
> Inspect agent task execution and configure a Flow node with sample input before testing its output
Debug tools help identify and resolve issues in agent workflows through systematic error analysis, node-level testing, and execution tracing.
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
Test a Flow node
Use **Configure & test** from a Flow node to inspect its connected input variables, provide sample input, and review the node's test output.
Open your agent's [Flow](/02-building-agents/agent-fundamentals/flow-configuration/flow-configuration) and select the node you want to inspect.
In the node sidebar, select **Configure & test**.
Review the node's input variables from connected nodes. Use **Input method** and **Run sample input** to provide data for the test.
After sample input is available, use **Test output** to run the tool and review the result.
**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](/03-running-operations/task-management/task-executions/task-executions) for comprehensive monitoring guidance.
Go to Tasks page and select failed or problematic task execution.
See complete workflow execution with each node's status, duration, and output.
Click failed node to view error message, input data received, and attempted output.
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, 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
**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)
Test mode
Use **Test mode** in an agent's Flow to configure a bounded test run with the connections used by its trigger and integration nodes.
Open the agent's **Flow** and turn on **Test mode** beside the Flow status.
In **Set up test mode**, enter the maximum number of runs. Beam shows a supported range of 2–200 runs and stops after that limit to control costs.
Choose the connection for the trigger, then choose a connection for each integration used by the Flow. Use **All nodes** when that connection should be available to every relevant node.
Select **Start testing**, then inspect the resulting task executions and node output for errors or unexpected results.
Use Test mode after changing a prompt, connection, or Flow logic. For larger sets of repeatable inputs, see [Test Datasets](/03-running-operations/debugging-testing/test-datasets/test-datasets).
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
* 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
Rerun failed tasks after applying debugging fixes
Create test datasets to validate debugging improvements
Use AI-powered optimization to improve failing prompts
Monitor task execution results to identify issues
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.