strategic/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Common Issues and Solutions

Strategy Validation Errors

Error: "Strategy validation failed"

Solutions:

• Check JSON syntax
• Verify all required fields are present
• Check action types are valid
• Verify addresses are correct format
• Run strategic validate strategy.json for details

Execution Failures

Error: "Target not allowed"

Solutions:

• Verify protocol address is in allow-list
• Check executor configuration
• Verify address matches chain
• Add address to allow-list if needed

Error: "Insufficient gas"

Solutions:

• Increase gas limit in strategy
• Optimize strategy (reduce steps)
• Check gas price settings
• Review gas estimation

Error: "Guard failed"

Solutions:

• Review guard parameters
• Check guard context (oracle, adapter availability)
• Adjust guard thresholds if appropriate
• Review guard failure action (revert/warn/skip)

Flash Loan Issues

Error: "Unauthorized pool"

Solutions:

• Verify Aave Pool is in allowed pools
• Check pool address is correct for chain
• Add pool to allow-list

Error: "Flash loan repayment failed"

Solutions:

• Verify sufficient funds for repayment + premium
• Check swap execution in callback
• Review flash loan amount
• Ensure operations in callback are correct

Adapter Errors

Error: "Adapter not available"

Solutions:

• Verify protocol is configured for chain
• Check chain name matches
• Verify RPC endpoint is working
• Check protocol addresses in config

Error: "Invalid asset address"

Solutions:

• Verify asset address format
• Check address exists on chain
• Verify asset is supported by protocol
• Check address is not zero address

Price Oracle Issues

Error: "Oracle not found"

Solutions:

• Verify Chainlink oracle address
• Check oracle exists on chain
• Verify token has price feed
• Check RPC endpoint

Error: "Stale price data"

Solutions:

• Check oracle update frequency
• Verify RPC endpoint latency
• Adjust maxAgeSeconds in guard
• Use multiple price sources

Gas Estimation Issues

Error: "Gas estimation failed"

Solutions:

• Check RPC endpoint
• Verify strategy is valid
• Check executor address
• Review transaction complexity
• Use fork simulation for accurate estimate

Cross-Chain Issues

Error: "Bridge not configured"

Solutions:

• Verify bridge addresses
• Check chain selectors
• Verify bridge is supported
• Configure bridge in orchestrator

Error: "Message status unknown"

Solutions:

• Check bridge status endpoint
• Verify message ID format
• Check finality thresholds
• Review bridge documentation

Debugging Tips

Enable Verbose Logging

DEBUG=* strategic run strategy.json

Use Explain Mode

strategic run strategy.json --explain

Fork Simulation

strategic run strategy.json --simulate --fork $RPC_URL

Check Strategy

strategic validate strategy.json

Getting Help

1. Check logs for detailed error messages
2. Review strategy JSON syntax
3. Verify all addresses and configurations
4. Test on fork first
5. Start with simple strategies
6. Review documentation
7. Check GitHub issues

Prevention

• Always validate strategies before execution
• Test on fork before live execution
• Use guards for safety checks
• Start with small amounts
• Monitor gas usage
• Review transaction logs
• Keep addresses updated