Common Issues and Solutions

Comprehensive troubleshooting guide for common AINexLayer issues, including installation problems, performance issues, and configuration errors.

Overview

This guide covers the most common issues users encounter with AINexLayer and provides step-by-step solutions. Issues are organized by category for easy navigation.

Installation Issues

Docker Installation Problems

Issue: Docker Container Won't Start

Symptoms:

• Container exits immediately after starting

• Error messages in docker logs

• Port conflicts

Solutions:

# Check container logs
docker logs ainexlayer

# Check port availability
netstat -tulpn | grep :3000

# Restart with different port
docker run -p 8080:3001 alakinfotech/ainexlayer:latest

# Check system resources
docker system df
docker system prune -f

Issue: Permission Denied Errors

Symptoms:

• Permission denied when accessing storage

• Cannot write to mounted volumes

• File system errors

Solutions:

# Fix storage permissions
sudo chown -R $USER:$USER ./storage
chmod -R 755 ./storage

# Run with proper user
docker run --user $(id -u):$(id -g) alakinfotech/ainexlayer:latest

# Check volume mounts
docker run -v $(pwd)/storage:/app/server/storage alakinfotech/ainexlayer:latest

Issue: Out of Memory Errors

Symptoms:

• Container killed due to OOM

• Slow performance

• System becomes unresponsive

Solutions:

# Increase memory limits
docker run --memory=4g alakinfotech/ainexlayer:latest

# Check system memory
free -h
docker stats

# Optimize container resources
docker run --cpus=2 --memory=4g alakinfotech/ainexlayer:latest

Local Installation Problems

Issue: Node.js Version Conflicts

Symptoms:

• Module compatibility errors

• Build failures

• Runtime errors

Solutions:

# Check Node.js version
node --version
npm --version

# Use correct Node.js version
nvm install 18
nvm use 18

# Clear npm cache
npm cache clean --force

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Issue: Python Dependencies

Symptoms:

• Python module not found

• Scrapy installation failures

• Virtual environment issues

Solutions:

# Check Python version
python3 --version

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Fix Scrapy installation
pip install --upgrade pip
pip install scrapy

Configuration Issues

Environment Variables

Issue: Missing Environment Variables

Symptoms:

• Application fails to start

• Configuration errors

• Missing API keys

Solutions:

# Check environment variables
env | grep -E "(OPEN_AI_KEY|JWT_SECRET|VECTOR_DB)"

# Create .env file
cat > .env << EOF
OPEN_AI_KEY=your-openai-api-key
JWT_SECRET=your-jwt-secret
VECTOR_DB=lancedb
NODE_ENV=production
EOF

# Load environment variables
source .env

Issue: Invalid API Keys

Symptoms:

• Authentication failures

• API rate limit errors

• Model not found errors

Solutions:

# Test OpenAI API key
curl -H "Authorization: Bearer $OPEN_AI_KEY" \
     https://api.openai.com/v1/models

# Check API key format
echo $OPEN_AI_KEY | wc -c

# Regenerate API key
# Go to OpenAI dashboard and create new key

Database Configuration

Issue: Database Connection Failed

Symptoms:

• Cannot connect to database

• Connection timeout errors

• Authentication failures

Solutions:

# Check database status
docker ps | grep postgres

# Test database connection
psql -h localhost -U ainexlayer -d ainexlayer

# Reset database password
docker exec -it postgres psql -U postgres -c "ALTER USER ainexlayer PASSWORD 'newpassword';"

# Check database logs
docker logs postgres

Issue: Vector Database Issues

Symptoms:

• Vector search not working

• Embedding generation failures

• Index corruption

Solutions:

# Check vector database status
curl http://localhost:8080/health

# Rebuild vector index
curl -X POST http://localhost:3001/api/v1/vectors/rebuild

# Clear vector cache
rm -rf ./storage/vectors/*

Performance Issues

Slow Response Times

Issue: High Latency

Symptoms:

• Slow API responses

• Timeout errors

• Poor user experience

Solutions:

# Check system resources
htop
df -h
free -h

# Optimize Docker resources
docker run --cpus=4 --memory=8g alakinfotech/ainexlayer:latest

# Enable caching
export ENABLE_CACHE=true
export CACHE_TTL=3600

# Use faster AI models
export LLM_MODEL=gpt-3.5-turbo

Issue: Memory Usage Issues

Symptoms:

• High memory consumption

• System slowdown

• Out of memory errors

Solutions:

# Monitor memory usage
docker stats

# Limit memory usage
docker run --memory=4g --memory-swap=4g alakinfotech/ainexlayer:latest

# Optimize Node.js memory
export NODE_OPTIONS="--max-old-space-size=4096"

# Clear caches
curl -X POST http://localhost:3001/api/v1/cache/clear

Document Processing Issues

Issue: Slow Document Processing

Symptoms:

• Documents take long to process

• Processing queue backlog

• Timeout errors

Solutions:

# Check processing queue
curl http://localhost:3001/api/v1/processing/status

# Increase processing workers
export PROCESSING_WORKERS=4

# Optimize document chunking
export CHUNK_SIZE=1000
export CHUNK_OVERLAP=200

# Use faster embedding models
export EMBEDDING_MODEL=text-embedding-3-small

Issue: OCR Processing Failures

Symptoms:

• Image text not extracted

• OCR errors

• Poor text quality

Solutions:

# Check OCR dependencies
pip list | grep tesseract

# Install Tesseract
sudo apt-get install tesseract-ocr

# Test OCR
tesseract image.png output.txt

# Configure OCR settings
export OCR_LANGUAGE=eng
export OCR_ENGINE=tesseract

API Issues

Authentication Problems

Issue: JWT Token Errors

Symptoms:

• Invalid token errors

• Authentication failures

• Session expired

Solutions:

# Check JWT secret
echo $JWT_SECRET

# Generate new JWT secret
openssl rand -base64 32

# Clear invalid tokens
curl -X POST http://localhost:3001/api/v1/auth/logout

# Test authentication
curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:3001/api/v1/workspaces

Issue: API Rate Limiting

Symptoms:

• Rate limit exceeded errors

• 429 HTTP status codes

• API quota issues

Solutions:

# Check rate limits
curl http://localhost:3001/api/v1/system/limits

# Increase rate limits
export RATE_LIMIT_WINDOW=900000
export RATE_LIMIT_MAX=1000

# Implement request queuing
export ENABLE_QUEUE=true
export QUEUE_SIZE=100

Webhook Issues

Issue: Webhook Delivery Failures

Symptoms:

• Webhooks not received

• Delivery timeout errors

• Invalid signatures

Solutions:

# Check webhook status
curl http://localhost:3001/api/v1/webhooks/status

# Test webhook endpoint
curl -X POST http://localhost:3001/api/v1/webhooks/test \
     -H "Content-Type: application/json" \
     -d '{"url": "https://your-app.com/webhook"}'

# Verify webhook signature
# Check signature verification in your webhook handler

File and Storage Issues

File Upload Problems

Issue: File Upload Failures

Symptoms:

• Upload timeout errors

• File size limit exceeded

• Invalid file format

Solutions:

# Check file size limits
export MAX_FILE_SIZE=100MB

# Increase upload timeout
export UPLOAD_TIMEOUT=300000

# Check supported formats
curl http://localhost:3001/api/v1/supported-formats

# Test file upload
curl -X POST http://localhost:3001/api/v1/documents/upload \
     -F "[email protected]"

Issue: Storage Space Issues

Symptoms:

• Disk space full

• Storage errors

• File system errors

Solutions:

# Check disk space
df -h

# Clean up old files
find ./storage -name "*.tmp" -mtime +7 -delete

# Compress old documents
tar -czf old_documents.tar.gz ./storage/old_documents/

# Move to external storage
aws s3 sync ./storage s3://your-backup-bucket/

Vector Database Issues

Issue: Vector Search Not Working

Symptoms:

• Search returns no results

• Vector similarity errors

• Index corruption

Solutions:

# Check vector database health
curl http://localhost:3001/api/v1/vectors/health

# Rebuild vector index
curl -X POST http://localhost:3001/api/v1/vectors/rebuild

# Check embedding generation
curl -X POST http://localhost:3001/api/v1/embeddings/generate \
     -H "Content-Type: application/json" \
     -d '{"text": "test document"}'

Network and Connectivity Issues

Port and Firewall Issues

Issue: Port Already in Use

Symptoms:

• Port binding errors

• Service won't start

• Connection refused

Solutions:

# Check port usage
netstat -tulpn | grep :3000
lsof -i :3000

# Kill process using port
sudo kill -9 $(lsof -t -i:3000)

# Use different port
docker run -p 8080:3001 alakinfotech/ainexlayer:latest

# Check firewall
sudo ufw status
sudo ufw allow 3000

Issue: Network Connectivity

Symptoms:

• Cannot reach external APIs

• DNS resolution failures

• Proxy issues

Solutions:

# Test network connectivity
ping google.com
curl -I https://api.openai.com

# Check DNS
nslookup api.openai.com

# Configure proxy
export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080

# Test with proxy
curl --proxy http://proxy:8080 https://api.openai.com

AI Model Issues

Model Configuration Problems

Issue: Model Not Found

Symptoms:

• Model not available errors

• Invalid model name

• API key issues

Solutions:

# Check available models
curl -H "Authorization: Bearer $OPEN_AI_KEY" \
     https://api.openai.com/v1/models

# Test model access
curl -X POST https://api.openai.com/v1/chat/completions \
     -H "Authorization: Bearer $OPEN_AI_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "test"}]}'

# Use fallback model
export FALLBACK_MODEL=gpt-3.5-turbo

Issue: Embedding Generation Failures

Symptoms:

• Embedding API errors

• Vector dimension mismatches

• Rate limit issues

Solutions:

# Test embedding API
curl -X POST https://api.openai.com/v1/embeddings \
     -H "Authorization: Bearer $OPEN_AI_KEY" \
     -H "Content-Type: application/json" \
     -d '{"input": "test text", "model": "text-embedding-3-small"}'

# Check embedding dimensions
export EMBEDDING_DIMENSIONS=1536

# Use local embeddings
export EMBEDDING_PROVIDER=sentence-transformers
export EMBEDDING_MODEL=all-MiniLM-L6-v2

Logging and Debugging

Enable Debug Logging

Issue: Insufficient Logging

Symptoms:

• Hard to diagnose issues

• Missing error details

• Poor troubleshooting

Solutions:

# Enable debug logging
export LOG_LEVEL=debug
export DEBUG=ainexlayer:*

# Check log files
tail -f ./logs/ainexlayer.log
tail -f ./logs/error.log

# Enable request logging
export ENABLE_REQUEST_LOGGING=true

# Check system logs
journalctl -u ainexlayer -f

Performance Monitoring

Issue: Performance Degradation

Symptoms:

• Slow system performance

• High resource usage

• Poor user experience

Solutions:

# Monitor system performance
htop
iotop
nethogs

# Check application metrics
curl http://localhost:3001/api/v1/metrics

# Enable performance monitoring
export ENABLE_METRICS=true
export METRICS_PORT=9090

# Check database performance
EXPLAIN ANALYZE SELECT * FROM documents WHERE workspace_id = '123';

Recovery Procedures

Data Recovery

Issue: Data Loss

Symptoms:

• Missing documents

• Corrupted data

• Database errors

Solutions:

# Check database integrity
pg_dump -h localhost -U ainexlayer ainexlayer > backup.sql

# Restore from backup
psql -h localhost -U ainexlayer ainexlayer < backup.sql

# Rebuild vector index
curl -X POST http://localhost:3001/api/v1/vectors/rebuild

# Check file system
fsck /dev/sda1

System Recovery

Issue: System Failure

Symptoms:

• Service won't start

• Complete system failure

• Data corruption

Solutions:

# Restart services
docker-compose down
docker-compose up -d

# Check system health
docker-compose ps
docker-compose logs

# Restore from backup
tar -xzf backup.tar.gz
docker-compose up -d

# Verify system health
curl http://localhost:3001/api/v1/system/health

Prevention and Best Practices

Regular Maintenance

System Health Checks

#!/bin/bash
# health-check.sh

# Check system resources
echo "=== System Resources ==="
free -h
df -h

# Check service status
echo "=== Service Status ==="
docker-compose ps

# Check API health
echo "=== API Health ==="
curl -f http://localhost:3001/api/v1/system/health

# Check database
echo "=== Database Status ==="
docker exec postgres pg_isready -U ainexlayer

# Check logs for errors
echo "=== Recent Errors ==="
tail -n 100 ./logs/error.log | grep ERROR

Automated Monitoring

#!/bin/bash
# monitor.sh

# Monitor system metrics
while true; do
    # Check CPU usage
    CPU_USAGE=$(top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1)

    # Check memory usage
    MEM_USAGE=$(free | grep Mem | awk '{printf("%.2f"), $3/$2 * 100.0}')

    # Check disk usage
    DISK_USAGE=$(df / | tail -1 | awk '{print $5}' | cut -d'%' -f1)

    # Alert if thresholds exceeded
    if (( $(echo "$CPU_USAGE > 80" | bc -l) )); then
        echo "High CPU usage: $CPU_USAGE%"
    fi

    if (( $(echo "$MEM_USAGE > 80" | bc -l) )); then
        echo "High memory usage: $MEM_USAGE%"
    fi

    if [ $DISK_USAGE -gt 80 ]; then
        echo "High disk usage: $DISK_USAGE%"
    fi

    sleep 60
done

Backup Procedures

Automated Backups

#!/bin/bash
# backup.sh

# Create backup directory
BACKUP_DIR="/backups/$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR

# Backup database
docker exec postgres pg_dump -U ainexlayer ainexlayer > $BACKUP_DIR/database.sql

# Backup application data
tar -czf $BACKUP_DIR/storage.tar.gz ./storage/

# Backup configuration
cp .env $BACKUP_DIR/
cp docker-compose.yml $BACKUP_DIR/

# Upload to cloud storage
aws s3 sync $BACKUP_DIR s3://your-backup-bucket/$(date +%Y%m%d)/

# Clean up old backups
find /backups -type d -mtime +7 -exec rm -rf {} \;

Getting Help

Support Channels

Documentation

• User Guide: Comprehensive user documentation

• API Reference: Complete API documentation

• Troubleshooting: This troubleshooting guide

• FAQ: Frequently asked questions

Community Support

• GitHub Issues: Report bugs and request features

• Discord Community: Real-time community support

• Stack Overflow: Technical questions and answers

• Reddit: General discussions and tips

Professional Support

• Email Support: [email protected]

• Priority Support: For enterprise customers

• Custom Development: Tailored solutions

• Training: Professional training services

Reporting Issues

Issue Template

## Issue Description
Brief description of the issue

## Steps to Reproduce
1. Step 1
2. Step 2
3. Step 3

## Expected Behavior
What you expected to happen

## Actual Behavior
What actually happened

## Environment
- OS: [e.g., Ubuntu 20.04]
- Docker version: [e.g., 20.10.7]
- AINexLayer version: [e.g., 1.8.5]

## Logs

Paste relevant logs here

## Additional Context
Any additional information that might be helpful

---

🔧 This troubleshooting guide covers the most common issues and solutions. For additional help, consult the support channels or contact our support team.