# Troubleshooting Guide

## Common Issues and Solutions

---

## Frontend Issues

### Issue: Hydration Errors
**Symptoms**: Console warnings about hydration mismatches
**Solution**: 
- Ensure all client-only components use `"use client"`
- Check for conditional rendering based on `window` or browser APIs
- Use `useEffect` for client-side only code

### Issue: Wallet Connection Fails
**Symptoms**: Wallet popup doesn't appear or connection fails
**Solution**:
- Check browser console for errors
- Verify wallet extension is installed
- Check network connectivity
- Clear browser cache and try again

### Issue: API Calls Fail
**Symptoms**: Network errors, 500 status codes
**Solution**:
- Verify `NEXT_PUBLIC_ORCH_URL` is set correctly
- Check orchestrator service is running
- Verify CORS configuration
- Check browser network tab for detailed errors

---

## Backend Issues

### Issue: Database Connection Fails
**Symptoms**: "Database connection error" in logs
**Solution**:
- Verify DATABASE_URL is correct
- Check database is running and accessible
- Verify network connectivity
- Check firewall rules

### Issue: Rate Limiting Too Aggressive
**Symptoms**: "Too many requests" errors
**Solution**:
- Adjust rate limit configuration in `rateLimit.ts`
- Check if IP is being shared
- Verify rate limit window settings

### Issue: Plan Execution Fails
**Symptoms**: Execution status shows "failed"
**Solution**:
- Check execution logs for specific error
- Verify all adapters are whitelisted
- Check DLT connection status
- Verify plan signature is valid

---

## Database Issues

### Issue: Migration Fails
**Symptoms**: Migration errors during startup
**Solution**:
- Check database permissions
- Verify schema doesn't already exist
- Check migration scripts for syntax errors
- Review database logs

### Issue: Query Performance Issues
**Symptoms**: Slow API responses
**Solution**:
- Check database indexes are created
- Review query execution plans
- Consider adding additional indexes
- Check connection pool settings

---

## Smart Contract Issues

### Issue: Contract Deployment Fails
**Symptoms**: Deployment reverts or fails
**Solution**:
- Verify sufficient gas
- Check contract dependencies
- Verify constructor parameters
- Review contract compilation errors

### Issue: Transaction Reverts
**Symptoms**: Transactions revert on execution
**Solution**:
- Check error messages in transaction receipt
- Verify adapter is whitelisted
- Check gas limits
- Verify signature is valid

---

## Monitoring Issues

### Issue: Metrics Not Appearing
**Symptoms**: Prometheus metrics endpoint empty
**Solution**:
- Verify metrics are being recorded
- Check Prometheus configuration
- Verify service is running
- Check network connectivity

---

## Security Issues

### Issue: API Key Authentication Fails
**Symptoms**: 401/403 errors
**Solution**:
- Verify API key is correct
- Check API key format
- Verify key is in ALLOWED_KEYS
- Check request headers

---

## Performance Issues

### Issue: Slow API Responses
**Symptoms**: High latency
**Solution**:
- Check database query performance
- Verify Redis caching is working
- Review connection pool settings
- Check external service response times

---

## Getting Help

1. Check logs: `kubectl logs <pod-name>` or `docker logs <container>`
2. Review metrics: `/metrics` endpoint
3. Check health: `/health` endpoint
4. Review error messages in application logs

---

**Last Updated**: 2025-01-15