Skip to main content

Troubleshooting

Solutions for common issues across all OLIVE services.

Quick Diagnostics

1

Check Service Health

curl http://localhost:8080/health  # Gateway
curl http://localhost:8000/health  # Agent
2

View Logs

docker compose logs -f gateway wallet-core agent
3

Check Database

psql $DATABASE_URL -c "SELECT 1"

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:
CauseSolution
Wallet-Core not runningdocker compose up wallet-core
Wrong addressCheck WALLET_CORE_ADDRESS in config
TLS mismatchVerify TLS settings match on both services
Network issueCheck firewall rules, verify network connectivity
# Verify Wallet-Core is running
docker compose ps wallet-core

# Check Gateway config
grep WALLET_CORE gateway/.env

401 Unauthorized

  • All API requests return 401
  • “Invalid token” or “Unauthorized” in response
Causes & Solutions:
CauseSolution
Missing headerInclude Authorization: Bearer <token>
Invalid API keyVerify key exists and is active
Expired JWTRefresh token or re-authenticate
Wrong secretCheck JWT_SECRET matches between services
# Test with API key
curl -H "Authorization: Bearer olive_live_xxx" \
  http://localhost:8080/api/v1/health

# Check if key exists in database
psql $DATABASE_URL -c "SELECT * FROM api_keys WHERE key_hash = ..."

403 Forbidden

  • Valid auth but access denied
  • “Insufficient permissions” error
Causes & Solutions:
CauseSolution
Wrong roleUser lacks required role for endpoint
Wrong scopesAPI key missing required scope
PEP restrictionPEP access requires OTP verification

429 Rate Limited

  • Requests start failing after high volume
  • X-RateLimit-Remaining: 0 in response
Solution:
# Increase rate limits in gateway/config.yaml
rate_limit:
  requests_per_second: 200  # Increase from 100
  burst: 400                # Increase from 200

Agent-TS Issues

OpenAI API Errors

  • Agent not responding to messages
  • “OpenAI API error” in logs
  • Timeout errors
Causes & Solutions:
CauseSolution
Invalid API keyVerify OPENAI_API_KEY in .env
Quota exceededCheck OpenAI billing/usage
Network blockedVerify outbound HTTPS to api.openai.com
Rate limitedAdd retry logic or reduce request rate
# Test OpenAI connectivity
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

KYC Image Processing Failed

  • “Invalid image” or “Processing failed” messages
  • OCR returns empty results
  • S3 upload errors
Causes & Solutions:
CauseSolution
Missing data URIEnsure media.data includes data:image/jpeg;base64,...
Invalid formatOnly JPEG and PNG supported
AWS credentialsVerify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
S3 permissionsCheck bucket policy allows PutObject
# Test S3 access
aws s3 ls s3://${AWS_S3_BUCKET_NAME}

# Verify image format
echo "$IMAGE_DATA" | head -c 50
# Should start with: data:image/jpeg;base64,

Assistant Not Calling Functions

  • Agent responds but doesn’t perform actions
  • No function calls in logs
  • Generic responses instead of wallet operations
Causes & Solutions:
CauseSolution
Assistant not createdCheck OPENAI_ASSISTANT_ID is set
Tools not registeredVerify tools in olive-agent.ts
Context lostCheck conversation history management
# Check assistant exists
curl https://api.openai.com/v1/assistants/${OPENAI_ASSISTANT_ID} \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Wallet-Core Issues

Database Connection Failed

  • Service won’t start
  • “Failed to connect to database” in logs
  • Migrations fail
Causes & Solutions:
CauseSolution
Invalid DSNCheck DATABASE_URL format
Database not runningStart PostgreSQL container
Network issueVerify database host is accessible
Wrong credentialsConfirm username/password
# Test database connection
psql $DATABASE_URL -c "SELECT version()"

# Check DATABASE_URL format
# postgresql://user:password@host:5432/database

Migrations Failed

  • Tables don’t exist
  • Schema mismatch errors
  • “relation does not exist” SQL errors
Causes & Solutions:
CauseSolution
PermissionsEnsure user has CREATE TABLE permission
Existing tablesCheck for conflicting tables
Migration errorCheck logs for specific error
# Manually run migrations
cd wallet-core
go run cmd/migrate/main.go -config config.yaml

# Check table existence
psql $DATABASE_URL -c "\dt"

Duplicate Transactions

  • Same transaction appears multiple times
  • Balance incorrect
Causes & Solutions:
CauseSolution
Reused request_idGenerate unique UUID for each request
Client retryImplement proper retry with same request_id
Missing idempotencyAlways 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

CodeNameMeaningAction
400Bad RequestInvalid request bodyCheck request format and required fields
401UnauthorizedInvalid/missing authVerify credentials
402Payment RequiredInsufficient balanceCheck user balance before payment
403ForbiddenAccess deniedCheck user role and permissions
404Not FoundResource doesn’t existVerify ID/phone number
409ConflictDuplicate resourceResource already exists
422UnprocessableValidation failedCheck field constraints
429Too Many RequestsRate limitedReduce request rate
500Internal ErrorServer errorCheck server logs
503UnavailableService downCheck dependent services

Log Analysis

Gateway Logs

# Filter by request ID
docker compose logs gateway | grep "request_id=abc123"

# Filter errors only
docker compose logs gateway | grep "level=error"

# Filter by endpoint
docker compose logs gateway | grep "POST /api/v1/payments"

Common Log Patterns

PatternMeaning
level=errorError occurred
status=401Authentication failed
status=500Internal error
grpc_errorWallet-Core communication issue
timeoutRequest took too long

Performance Issues

Slow Response Times

  • API responses take > 1 second
  • Timeouts on some requests
Diagnosis & Solutions:
# Check database query times
psql $DATABASE_URL -c "SELECT * FROM pg_stat_statements ORDER BY mean_time DESC LIMIT 5"

# Check connection pool
psql $DATABASE_URL -c "SELECT count(*) FROM pg_stat_activity"

# Add missing indexes
psql $DATABASE_URL -c "CREATE INDEX idx_transactions_user_id ON transactions(user_id)"

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