Troubleshooting Overview

Comprehensive guide to diagnosing and resolving common issues with Alactic AGI.

Quick Diagnostics

Health Check Endpoints

# Check API health
curl https://your-deployment.azurewebsites.net/health

# Expected response
{
  "status": "healthy",
  "timestamp": "2025-12-19T10:30:00Z",
  "services": {
    "api": "up",
    "solr": "up",
    "storage": "up"
  }
}

Common Quick Fixes

1. Clear browser cache and cookies
2. Verify API key is active in Azure Portal
3. Check service quotas haven't been exceeded
4. Restart the application in Azure Portal

Common Issues

Authentication Errors

Issue: "Invalid API Key"

Symptoms: 401 Unauthorized responses

Solutions:

• Verify API key in Azure Portal → Your Resource → Keys and Endpoints
• Check key hasn't expired or been rotated
• Ensure key is properly encoded in Authorization header
• Verify you're using the correct endpoint URL

Issue: "Rate Limit Exceeded"

Symptoms: 429 Too Many Requests

Solutions:

• Check current usage in Azure Portal
• Upgrade to higher tier plan
• Implement exponential backoff in your application
• Review and optimize request patterns

Document Processing Issues

Issue: "Document Processing Failed"

Symptoms: Error response when uploading documents

Solutions:

• Verify document size is under plan limit (check plans page)
• Ensure document format is supported (PDF, DOCX, TXT)
• Check document isn't corrupted or password-protected
• Verify sufficient storage quota available

Issue: "Timeout During Processing"

Symptoms: Request times out after 30-60 seconds

Solutions:

• Break large documents into smaller chunks
• Use batch processing API for multiple documents
• Increase timeout in your HTTP client
• Check VM size is appropriate for workload

Web Scraping Issues

Issue: "Unable to Scrape Website"

Symptoms: Empty results or error messages

Solutions:

• Verify website allows scraping (check robots.txt)
• Test if site requires JavaScript rendering
• Check if site is blocking Azure IP ranges
• Ensure URL is accessible from Azure region
• Try with different User-Agent headers

Issue: "Inconsistent Scraping Results"

Symptoms: Different results on different runs

Solutions:

• Site may have dynamic content - use consistent timing
• Check if site uses anti-bot measures
• Implement proper request delays
• Consider using premium scraping options

Error Code Reference

4xx Client Errors

Code	Message	Cause	Solution
400	Bad Request	Malformed request	Check request format and required fields
401	Unauthorized	Invalid/missing API key	Verify API key in request headers
403	Forbidden	Insufficient permissions	Check plan tier and feature access
404	Not Found	Invalid endpoint/resource	Verify URL and resource ID
409	Conflict	Resource already exists	Use different name or update existing
413	Payload Too Large	File exceeds size limit	Reduce file size or upgrade plan
429	Too Many Requests	Rate limit exceeded	Implement backoff, upgrade plan

5xx Server Errors

Code	Message	Cause	Solution
500	Internal Server Error	Unexpected server issue	Retry request, contact support if persists
502	Bad Gateway	Service temporarily down	Wait and retry with backoff
503	Service Unavailable	Maintenance or overload	Check status page, retry later
504	Gateway Timeout	Request took too long	Reduce request size, use batch API

Performance Issues

Slow Response Times

Symptoms: Requests taking longer than expected

Diagnostic Steps:

1. Check Azure Portal metrics for CPU/memory usage
2. Review application logs for bottlenecks
3. Verify network latency from your location
4. Check if concurrent request limit reached

Solutions:

• Upgrade to higher VM size
• Optimize document size before processing
• Use batch processing for multiple items
• Implement caching for frequently accessed data
• Consider multi-region deployment

High Memory Usage

Symptoms: Out of memory errors, crashes

Solutions:

• Process documents in smaller batches
• Upgrade to plan with more RAM
• Implement streaming for large files
• Clear cache regularly
• Monitor and tune Solr memory settings

Diagnostic Tools

Azure Portal Diagnostics

1. Application Insights

   • View request traces
   • Monitor exceptions
   • Analyze performance
   • Set up alerts

2. Log Stream

   • Real-time log viewing
   • Filter by log level
   • Search for errors
   • Download logs

3. Metrics Explorer

   • CPU and memory usage
   • Request rates
   • Response times
   • Error rates

API Diagnostics

import requests
import json

# Get detailed diagnostics
response = requests.get(
    "https://your-deployment.azurewebsites.net/api/diagnostics",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

diagnostics = response.json()
print(json.dumps(diagnostics, indent=2))

Log Analysis

# View recent errors
az webapp log tail --name your-app-name --resource-group your-rg

# Download logs
az webapp log download --name your-app-name --resource-group your-rg --log-file logs.zip

Integration Issues

Azure Blob Storage

Issue: Can't access documents in Blob Storage

Solutions:

• Verify storage account connection string
• Check SAS token hasn't expired
• Ensure blob container permissions are correct
• Verify network rules allow access from your VM

Webhook Failures

Issue: Webhooks not triggering

Solutions:

• Verify webhook endpoint is publicly accessible
• Check webhook URL is correctly configured
• Review webhook logs in Azure Portal
• Ensure endpoint responds within timeout (30s)
• Verify SSL certificate is valid

Getting Help

Before Contacting Support

Gather the following information:

• Deployment name and resource group
• Timestamp of issue occurrence
• Full error message and error code
• Request ID from error response
• Steps to reproduce the issue
• Current plan tier

Support Channels

1. Documentation Search

   • Check API reference
   • Review integration guides
   • Read best practices

2. Common Issues

   • Review this troubleshooting guide
   • Check Azure status page
   • Search known issues

3. Support Ticket

   • Visit alactic.io/support
   • Include diagnostic information
   • Attach relevant logs
   • Specify priority level

Emergency Contacts

For critical production issues:

• Email: support@alacticai.com
• Portal: Azure Portal → Your Resource → Support
• SLA: Enterprise plans get 24/7 support

Preventive Measures

Regular Maintenance

• Weekly: Review error logs and metrics
• Monthly: Update to latest version
• Quarterly: Review and optimize costs
• Annually: Conduct disaster recovery testing

Monitoring Setup

# Recommended alerts
alerts:
  - metric: cpu_percentage
    threshold: 80
    duration: 5m
    
  - metric: memory_percentage
    threshold: 85
    duration: 5m
    
  - metric: response_time
    threshold: 3s
    duration: 10m
    
  - metric: error_rate
    threshold: 5%
    duration: 5m

Best Practices

• Implement comprehensive error handling
• Use retry logic with exponential backoff
• Monitor resource usage regularly
• Keep API keys secure and rotate periodically
• Test changes in non-production environment first
• Document integration points and dependencies
• Maintain up-to-date runbooks

Additional Resources

• Common Issues Detailed Guide
• API Error Reference
• Performance Tuning
• Monitoring Guide
• Azure Support Documentation