Skip to main content

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

  • Gateway health shows wallet_core: unavailable
  • 500 errors on payment endpoints
  • Logs show gRPC connection errors
Causes & Solutions:

401 Unauthorized

  • All API requests return 401
  • “Invalid token” or “Unauthorized” in response
Causes & Solutions:

403 Forbidden

  • Valid auth but access denied
  • “Insufficient permissions” error
Causes & Solutions:

429 Rate Limited

  • Requests start failing after high volume
  • X-RateLimit-Remaining: 0 in response
Solution:

Agent-TS Issues

OpenAI API Errors

  • Agent not responding to messages
  • “OpenAI API error” in logs
  • Timeout errors
Causes & Solutions:

KYC Image Processing Failed

  • “Invalid image” or “Processing failed” messages
  • OCR returns empty results
  • S3 upload errors
Causes & Solutions:

Assistant Not Calling Functions

  • Agent responds but doesn’t perform actions
  • No function calls in logs
  • Generic responses instead of wallet operations
Causes & Solutions:

Wallet-Core Issues

Database Connection Failed

  • Service won’t start
  • “Failed to connect to database” in logs
  • Migrations fail
Causes & Solutions:

Migrations Failed

  • Tables don’t exist
  • Schema mismatch errors
  • “relation does not exist” SQL errors
Causes & Solutions:

Duplicate Transactions

  • Same transaction appears multiple times
  • Balance incorrect
Causes & Solutions:
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

  • API responses take > 1 second
  • Timeouts on some requests
Diagnosis & Solutions:

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