Troubleshooting
Solutions for common issues across all OLIVE services.Quick Diagnostics
1
Check Service Health
2
View Logs
3
Check Database
Gateway Issues
Connection to Wallet-Core Failed
Symptoms
Symptoms
- Gateway health shows
wallet_core: unavailable - 500 errors on payment endpoints
- Logs show gRPC connection errors
401 Unauthorized
Symptoms
Symptoms
- All API requests return 401
- “Invalid token” or “Unauthorized” in response
403 Forbidden
Symptoms
Symptoms
- Valid auth but access denied
- “Insufficient permissions” error
429 Rate Limited
Symptoms
Symptoms
- Requests start failing after high volume
X-RateLimit-Remaining: 0in response
Agent-TS Issues
OpenAI API Errors
Symptoms
Symptoms
- Agent not responding to messages
- “OpenAI API error” in logs
- Timeout errors
KYC Image Processing Failed
Symptoms
Symptoms
- “Invalid image” or “Processing failed” messages
- OCR returns empty results
- S3 upload errors
Assistant Not Calling Functions
Symptoms
Symptoms
- Agent responds but doesn’t perform actions
- No function calls in logs
- Generic responses instead of wallet operations
Wallet-Core Issues
Database Connection Failed
Symptoms
Symptoms
- Service won’t start
- “Failed to connect to database” in logs
- Migrations fail
Migrations Failed
Symptoms
Symptoms
- Tables don’t exist
- Schema mismatch errors
- “relation does not exist” SQL errors
Duplicate Transactions
Symptoms
Symptoms
- Same transaction appears multiple times
- Balance incorrect
OLIVE uses idempotency keys. If you retry with the same
request_id, the original transaction is returned instead of creating a duplicate.Common Error Codes
Log Analysis
Gateway Logs
Common Log Patterns
Performance Issues
Slow Response Times
Symptoms
Symptoms
- API responses take > 1 second
- Timeouts on some requests
Getting Help
Check Logs
Always check service logs first
Health Endpoints
Use /health for quick diagnostics
GitHub Issues
Search existing issues for solutions
Documentation
Review relevant docs sections