Troubleshooting

❌ Problem: "Connection refused" when registering service

Symptoms: Client throws connection errors when trying to register

Error: Request failed with status code ECONNREFUSED
at ScoutQuestClient.registerService (client.js:45)

// Or in Rust:
Error: Network error: Connection refused (os error 61)

Causes & Solutions:

• ScoutQuest server not running: Start the server with ./scoutquest-server
• Wrong server URL: Check if using correct host and port (default: http://localhost:8080)
• Firewall blocking: Ensure port 8080 is open and accessible
• Network connectivity: Test with curl http://localhost:8080/health

❌ Problem: Service registration succeeds but service not discoverable

Symptoms: Registration returns success but discoverService() fails

// Registration succeeds
const instance = await client.registerService('my-service', 'localhost', 3000);
console.log('Registered:', instance.id); // Works

// Discovery fails
const discovered = await client.discoverService('my-service'); // ServiceNotFoundError

Solutions:

• Check service name spelling: Service names are case-sensitive
• Verify health status: Service might be registered but marked unhealthy
• Database issues: Check server logs for database connection errors
• Cache issues: Clear discovery cache or wait for TTL expiration

❌ Problem: Health check failures

Symptoms: Services registered but marked as unhealthy

// Health check endpoint not responding
GET http://localhost:3000/health → 404 Not Found

// Or timeout
Error: Health check timeout after 5000ms

Solutions:

• Implement health endpoint: Add /health endpoint to your service
• Check endpoint path: Ensure health check URL is correct
• Verify service is running: Test service accessibility directly
• Adjust timeout: Increase health check timeout in configuration

❌ Problem: "ServiceNotFoundError" for existing services

Symptoms: Service exists but cannot be discovered

ScoutQuestError: Service 'user-service' not found
    at ServiceDiscoveryClient.discoverService

Debug Steps:

# 1. List all services
curl http://localhost:8080/api/services

# 2. Check specific service instances
curl http://localhost:8080/api/services/user-service/instances

# 3. Verify service registration
curl -X POST http://localhost:8080/api/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user-service",
    "host": "localhost",
    "port": 3000
  }'

❌ Problem: Load balancing not working

Symptoms: Always get same instance, no distribution

Solutions:

• Multiple instances: Ensure multiple healthy instances are registered
• Check strategy: Verify load balancing strategy configuration
• Clear cache: Discovery cache might return same cached instance

// Force fresh discovery (bypass cache)
const options = {
  bypassCache: true,
  loadBalancingStrategy: 'round_robin'
};
const instance = await client.discoverServiceWithOptions('user-service', options);

❌ Problem: HTTP requests through ScoutQuest fail

Symptoms: Direct calls work, but calls through discovery fail

// Direct call works
const response = await fetch('http://localhost:3000/api/users');

// Through ScoutQuest fails
const response = await client.getService('user-service', '/api/users'); // Error

Debug approach:

// 1. Verify service discovery works
const instance = await client.discoverService('user-service');
console.log('Discovered:', instance);

// 2. Test direct call to discovered instance
const directResponse = await fetch(`http://${instance.host}:${instance.port}/api/users`);
console.log('Direct call status:', directResponse.status);

// 3. Enable debug logging
const client = new ScoutQuestClient({
  serverUrl: 'http://localhost:8080',
  debug: true
});

❌ Problem: Timeout errors

Symptoms: Requests timeout inconsistently

ScoutQuestError: Request timeout after 5000ms

Solutions:

• Increase timeout: Adjust client timeout configuration
• Check service performance: Monitor target service response times
• Network issues: Verify network connectivity and latency

// Increase timeout for specific calls
const response = await client.getService('slow-service', '/api/data', {
  timeout: 30000 // 30 seconds
});

❌ Problem: ScoutQuest server won't start

Common error messages and solutions:

# Error: Address already in use
Error: Address already in use (os error 48)

Solution: Another process using port 8080

# Find process using port 8080
lsof -i :8080
kill -9 

# Or use different port
SCOUTQUEST_PORT=8081 ./scoutquest-server

# Error: Database connection failed
Error: Failed to connect to database: Connection refused

Solutions:

• Start PostgreSQL: brew services start postgresql (macOS) or sudo systemctl start postgresql (Linux)
• Create database: createdb scoutquest
• Check connection string in config file

❌ Problem: High memory usage

Symptoms: Server memory consumption grows over time

Diagnostic steps:

# Check memory usage
ps aux | grep scoutquest-server

# Monitor over time
watch -n 5 'ps aux | grep scoutquest-server'

# Check metrics endpoint
curl http://localhost:8080/metrics | grep memory

Solutions:

• Reduce cache size: Lower cache TTL and max size in configuration
• Connection pool limits: Reduce database connection pool size
• Service cleanup: Implement automatic deregistration of dead services

❌ Problem: Slow service discovery

Solutions:

• Enable caching: Use discovery cache with appropriate TTL
• Database optimization: Ensure proper indexes on services table
• Connection pooling: Use database connection pooling

// Enable client-side caching
const client = new ScoutQuestClient({
  serverUrl: 'http://localhost:8080',
  cache: {
    enabled: true,
    ttl: 60000, // 1 minute
    maxSize: 1000
  }
});

❌ Problem: High latency HTTP calls

Diagnostic approach:

# Measure different components
time curl http://localhost:8080/api/services/user-service  # Discovery time
time curl http://localhost:3000/api/users  # Direct service time
time scoutquest-client get user-service /api/users  # Through ScoutQuest

Solutions:

• Keep-alive connections: Enable HTTP keep-alive
• Connection pooling: Reuse HTTP connections
• Local instances: Prefer geographically closer instances