148 lines
3.4 KiB
Markdown
148 lines
3.4 KiB
Markdown
|
# 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
|
||
|
|
|