Skip to main content

Troubleshooting

This guide helps you diagnose and resolve common integration issues with Gentic.

Common Issues​

Connection Errors​

Database Connections​

// Enable debug logging for database connections
const dbSource = await client.createKnowledgeSource({
  name: 'Debug Database',
  type: 'postgresql',
  config: {
    host: 'localhost',
    port: 5432,
    database: 'mydb',
    debug: true // Enable detailed logging
  }
});

API Connections​

// Configure retry logic for API connections
const apiSource = await client.createKnowledgeSource({
  name: 'Retry API',
  type: 'rest',
  config: {
    baseUrl: 'https://api.example.com',
    retry: {
      attempts: 3,
      delay: 1000, // 1 second
      backoff: 'exponential'
    }
  }
});

Authentication Issues​

API Key Rotation​

// Implement API key rotation
const secureSource = await client.createKnowledgeSource({
  name: 'Secure API',
  type: 'rest',
  config: {
    baseUrl: 'https://api.example.com',
    auth: {
      type: 'api_key',
      rotation: {
        interval: '24h',
        gracePeriod: '1h'
      }
    }
  }
});

OAuth Tokens​

// Handle OAuth token refresh
const oauthSource = await client.createKnowledgeSource({
  name: 'OAuth API',
  type: 'rest',
  config: {
    baseUrl: 'https://api.example.com',
    auth: {
      type: 'oauth',
      refresh: {
        interval: '1h',
        onError: 'retry'
      }
    }
  }
});

Performance Issues​

Query Optimization​

// Optimize database queries
const optimizedSource = await client.createKnowledgeSource({
  name: 'Optimized DB',
  type: 'postgresql',
  config: {
    host: 'localhost',
    database: 'mydb',
    query: {
      timeout: 5000, // 5 seconds
      maxRows: 1000,
      cache: true
    }
  }
});

Rate Limiting​

// Handle rate limits
const rateLimitedSource = await client.createKnowledgeSource({
  name: 'Rate Limited API',
  type: 'rest',
  config: {
    baseUrl: 'https://api.example.com',
    rateLimit: {
      requests: 100,
      period: 'minute',
      strategy: 'queue'
    }
  }
});

Debugging Tools​

Logging​

// Configure detailed logging
const loggedSource = await client.createKnowledgeSource({
  name: 'Logged Source',
  type: 'any',
  config: {
    logging: {
      level: 'debug',
      format: 'json',
      fields: ['timestamp', 'operation', 'duration', 'error']
    }
  }
});

Metrics​

// Enable performance metrics
const monitoredSource = await client.createKnowledgeSource({
  name: 'Monitored Source',
  type: 'any',
  config: {
    metrics: {
      enabled: true,
      interval: '1m',
      export: 'prometheus'
    }
  }
});

Error Handling​

Workflow Error Handling​

const resilientWorkflow = await client.createWorkflow({
  name: 'Resilient Process',
  steps: [
    {
      type: 'try',
      steps: [
        {
          type: 'process',
          input: '{{data}}'
        }
      ],
      catch: [
        {
          type: 'retry',
          maxAttempts: 3,
          delay: 'exponential'
        },
        {
          type: 'fallback',
          action: 'notify_admin'
        }
      ]
    }
  ]
});

Circuit Breaker​

const protectedSource = await client.createKnowledgeSource({
  name: 'Protected API',
  type: 'rest',
  config: {
    baseUrl: 'https://api.example.com',
    circuitBreaker: {
      threshold: 5,
      timeout: 30000,
      resetTimeout: 60000
    }
  }
});

Monitoring​

Health Checks​

const monitoredSource = await client.createKnowledgeSource({
  name: 'Monitored Source',
  type: 'any',
  config: {
    healthCheck: {
      interval: '1m',
      timeout: 5000,
      alerts: ['slack', 'email']
    }
  }
});

Performance Monitoring​

const performanceSource = await client.createKnowledgeSource({
  name: 'Performance Source',
  type: 'any',
  config: {
    monitoring: {
      metrics: ['latency', 'throughput', 'error_rate'],
      alerts: {
        latency: '>1000ms',
        error_rate: '>1%'
      }
    }
  }
});

Next Steps​