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

```bash
DEBUG=* strategic run strategy.json
```

### Use Explain Mode

```bash
strategic run strategy.json --explain
```

### Fork Simulation

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

### Check Strategy

```bash
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