Troubleshooting
Solutions for common issues across all OLIVE services.Quick Diagnostics
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
| Cause | Solution |
|---|---|
| Wallet-Core not running | docker compose up wallet-core |
| Wrong address | Check WALLET_CORE_ADDRESS in config |
| TLS mismatch | Verify TLS settings match on both services |
| Network issue | Check firewall rules, verify network connectivity |
401 Unauthorized
Symptoms
Symptoms
- All API requests return 401
- “Invalid token” or “Unauthorized” in response
| Cause | Solution |
|---|---|
| Missing header | Include Authorization: Bearer <token> |
| Invalid API key | Verify key exists and is active |
| Expired JWT | Refresh token or re-authenticate |
| Wrong secret | Check JWT_SECRET matches between services |
403 Forbidden
Symptoms
Symptoms
- Valid auth but access denied
- “Insufficient permissions” error
| Cause | Solution |
|---|---|
| Wrong role | User lacks required role for endpoint |
| Wrong scopes | API key missing required scope |
| PEP restriction | PEP access requires OTP verification |
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
| Cause | Solution |
|---|---|
| Invalid API key | Verify OPENAI_API_KEY in .env |
| Quota exceeded | Check OpenAI billing/usage |
| Network blocked | Verify outbound HTTPS to api.openai.com |
| Rate limited | Add retry logic or reduce request rate |
KYC Image Processing Failed
Symptoms
Symptoms
- “Invalid image” or “Processing failed” messages
- OCR returns empty results
- S3 upload errors
| Cause | Solution |
|---|---|
| Missing data URI | Ensure media.data includes data:image/jpeg;base64,... |
| Invalid format | Only JPEG and PNG supported |
| AWS credentials | Verify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY |
| S3 permissions | Check bucket policy allows PutObject |
Assistant Not Calling Functions
Symptoms
Symptoms
- Agent responds but doesn’t perform actions
- No function calls in logs
- Generic responses instead of wallet operations
| Cause | Solution |
|---|---|
| Assistant not created | Check OPENAI_ASSISTANT_ID is set |
| Tools not registered | Verify tools in olive-agent.ts |
| Context lost | Check conversation history management |
Wallet-Core Issues
Database Connection Failed
Symptoms
Symptoms
- Service won’t start
- “Failed to connect to database” in logs
- Migrations fail
| Cause | Solution |
|---|---|
| Invalid DSN | Check DATABASE_URL format |
| Database not running | Start PostgreSQL container |
| Network issue | Verify database host is accessible |
| Wrong credentials | Confirm username/password |
Migrations Failed
Symptoms
Symptoms
- Tables don’t exist
- Schema mismatch errors
- “relation does not exist” SQL errors
| Cause | Solution |
|---|---|
| Permissions | Ensure user has CREATE TABLE permission |
| Existing tables | Check for conflicting tables |
| Migration error | Check logs for specific error |
Duplicate Transactions
Symptoms
Symptoms
- Same transaction appears multiple times
- Balance incorrect
| Cause | Solution |
|---|---|
| Reused request_id | Generate unique UUID for each request |
| Client retry | Implement proper retry with same request_id |
| Missing idempotency | Always include request_id in payments |
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
| Code | Name | Meaning | Action |
|---|---|---|---|
| 400 | Bad Request | Invalid request body | Check request format and required fields |
| 401 | Unauthorized | Invalid/missing auth | Verify credentials |
| 402 | Payment Required | Insufficient balance | Check user balance before payment |
| 403 | Forbidden | Access denied | Check user role and permissions |
| 404 | Not Found | Resource doesn’t exist | Verify ID/phone number |
| 409 | Conflict | Duplicate resource | Resource already exists |
| 422 | Unprocessable | Validation failed | Check field constraints |
| 429 | Too Many Requests | Rate limited | Reduce request rate |
| 500 | Internal Error | Server error | Check server logs |
| 503 | Unavailable | Service down | Check dependent services |
Log Analysis
Gateway Logs
Common Log Patterns
| Pattern | Meaning |
|---|---|
level=error | Error occurred |
status=401 | Authentication failed |
status=500 | Internal error |
grpc_error | Wallet-Core communication issue |
timeout | Request took too long |
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