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.

PreviousHR Automation Use Case NextPerformance Optimization

Last updated 5 months ago

Good morning

hashtagOverview

hashtagInstallation Issues

hashtagDocker Installation Problems

hashtagLocal Installation Problems

hashtagConfiguration Issues

hashtagEnvironment Variables

hashtagDatabase Configuration

hashtagPerformance Issues

hashtagSlow Response Times

hashtagDocument Processing Issues

hashtagAPI Issues

hashtagAuthentication Problems

hashtagWebhook Issues

hashtagFile and Storage Issues

hashtagFile Upload Problems

hashtagVector Database Issues

hashtagNetwork and Connectivity Issues

hashtagPort and Firewall Issues

hashtagAI Model Issues

hashtagModel Configuration Problems

hashtagLogging and Debugging

hashtagEnable Debug Logging

hashtagPerformance Monitoring

hashtagRecovery Procedures

hashtagData Recovery

hashtagSystem Recovery

hashtagPrevention and Best Practices

hashtagRegular Maintenance

hashtagBackup Procedures

hashtagGetting Help

hashtagSupport Channels

hashtagReporting Issues

Overview

Installation Issues

Docker Installation Problems

Local Installation Problems

Configuration Issues

Environment Variables

Database Configuration

Performance Issues

Slow Response Times

Document Processing Issues

API Issues

Authentication Problems

Webhook Issues

File and Storage Issues

File Upload Problems

Vector Database Issues

Network and Connectivity Issues

Port and Firewall Issues

AI Model Issues

Model Configuration Problems

Logging and Debugging

Enable Debug Logging

Performance Monitoring

Recovery Procedures

Data Recovery

System Recovery

Prevention and Best Practices

Regular Maintenance

Backup Procedures

Getting Help

Support Channels

Reporting Issues