Appendix D: Troubleshooting Checklist

Detta appendix ger strukturerade troubleshooting-checklistor för att snabbt diagnostisera och lösa vanliga problem i din lokala AI-infrastruktur. Checklistorna är organiserade efter symptom och systemkomponent.

D.1 Snabb Diagnostik - Första Steget

D.1.1 System Health Check (5 minuter)

🔍 Snabb översikt:

# 1. Kontrollera alla services status
docker-compose ps

# 2. Kontrollera system resources
free -h && df -h

# 3. Kontrollera GPU (om tillämpligt)
nvidia-smi

# 4. Kontrollera Docker status
docker system df

✅ Grundläggande kontrollista:

• [ ] Alla containers körs (status "Up")
• [ ] Ingen service är i restart loop
• [ ] Tillräckligt med RAM (>20% ledigt)
• [ ] Tillräckligt med disk space (>10% ledigt)
• [ ] GPU är tillgänglig och har ledigt VRAM
• [ ] Inga kritiska fel i logs senaste 10 minuterna

🚨 Om något är rött ovan:

1. Stoppa systemet: docker-compose down
2. Kontrollera logs: docker-compose logs --tail=50
3. Starta om: docker-compose up -d
4. Om fortfarande problem → gå till specifik sektion nedan

D.2 Service-Specifik Troubleshooting

D.2.1 Ollama Troubleshooting

💾 Problem: Ollama startar inte

Symptom:

• Container exit med fel
• "Connection refused" till port 11434
• Container startar men svarar inte på API calls

Diagnostik:

# Kontrollera container status
docker-compose ps ollama

# Kontrollera logs
docker-compose logs ollama --tail=50

# Testa manual start
docker-compose exec ollama ollama serve

Lösningar per feltyp:

🔧 Ollama Fix Commands:

# Restart med debug
OLLAMA_DEBUG=true docker-compose up -d ollama

# Rensa alla modeller och starta om
docker-compose exec ollama sh -c "rm -rf ~/.ollama/models/*"
docker-compose restart ollama

# Testa GPU access
docker-compose exec ollama nvidia-smi
docker-compose exec ollama ollama run llama3.1:8b "Hello"

# Fix permissions
sudo chown -R $(id -u):$(id -g) ./data/ollama

💾 Problem: Modeller laddar inte

Symptom:

• "model not found" errors
• Modeller finns i ollama list men kan inte användas
• Långsam model loading

Diagnostik:

# Lista modeller
docker-compose exec ollama ollama list

# Kontrollera model files
docker-compose exec ollama ls -la ~/.ollama/models/

# Kontrollera disk space
docker-compose exec ollama df -h ~/.ollama/

# Testa model loading
docker-compose exec ollama ollama run llama3.1:8b "test"

✅ Model Loading Checklist:

• [ ] Modell finns i ollama list
• [ ] Tillräckligt med disk space för modell
• [ ] Tillräckligt med VRAM/RAM för modell
• [ ] Modell inte korrupt (prova ollama pull igen)
• [ ] Ingen annan modell blockerar resources

🔧 Model Fix Commands:

# Re-download korrupt modell
docker-compose exec ollama ollama rm llama3.1:8b
docker-compose exec ollama ollama pull llama3.1:8b

# Frigör memory från andra modeller
docker-compose exec ollama ollama ps
# Stoppa onödiga modeller manuellt

# Kontrollera VRAM usage
docker-compose exec ollama nvidia-smi

D.2.2 Database (PostgreSQL) Troubleshooting

🗄️ Problem: Database connection fails

Symptom:

• "connection refused" errors
• "password authentication failed"
• Services kan inte connecta till databas

Diagnostik:

# Kontrollera container status
docker-compose ps postgres

# Testa database connection
docker-compose exec postgres pg_isready -U postgres

# Kontrollera logs
docker-compose logs postgres --tail=50

# Testa connection med credentials
docker-compose exec postgres psql -U $DB_USER -d $DB_NAME -c "SELECT 1;"

✅ Database Connection Checklist:

• [ ] PostgreSQL container körs
• [ ] Database credentials är korrekta i .env
• [ ] Database namn existerar
• [ ] Inga connection limit errors
• [ ] Network connectivity mellan services

🔧 Database Fix Commands:

# Restart database
docker-compose restart postgres

# Skapa database om den saknas
docker-compose exec postgres createdb -U postgres localai

# Reset lösenord
docker-compose exec postgres psql -U postgres -c "ALTER USER postgres PASSWORD 'new_password';"

# Kontrollera connections
docker-compose exec postgres psql -U postgres -c "SELECT * FROM pg_stat_activity;"

# Check database diskspace
docker-compose exec postgres df -h /var/lib/postgresql/data

🗄️ Problem: Database performance issues

Symptom:

• Långsamma queries
• Connection timeouts
• High CPU på database container

Diagnostik:

# Kontrollera aktiva connections
docker-compose exec postgres psql -U postgres -c "
SELECT count(*) as active_connections 
FROM pg_stat_activity 
WHERE state = 'active';"

# Kontrollera långsamma queries
docker-compose exec postgres psql -U postgres -c "
SELECT query, mean_exec_time, calls 
FROM pg_stat_statements 
ORDER BY mean_exec_time DESC 
LIMIT 5;"

# Kontrollera database size
docker-compose exec postgres psql -U postgres -c "
SELECT pg_size_pretty(pg_database_size('localai'));"

🔧 Database Performance Fixes:

# Vacuum och analyze
docker-compose exec postgres psql -U postgres -d localai -c "VACUUM ANALYZE;"

# Restart database för att rensa connections
docker-compose restart postgres

# Öka connection pool i .env
DB_POOL_SIZE=50
DB_MAX_OVERFLOW=100

# Kontrollera locks
docker-compose exec postgres psql -U postgres -c "
SELECT blocked_locks.pid AS blocked_pid,
       blocking_locks.pid AS blocking_pid
FROM pg_catalog.pg_locks blocked_locks
JOIN pg_catalog.pg_locks blocking_locks 
  ON blocking_locks.locktype = blocked_locks.locktype;"

D.2.3 Open WebUI Troubleshooting

🌐 Problem: WebUI inte tillgänglig

Symptom:

• "This site can't be reached"
• Blank sida eller loading forever
• 500 Internal Server Error

Diagnostik:

# Kontrollera container status
docker-compose ps webui

# Kontrollera logs
docker-compose logs webui --tail=50

# Testa internal API
docker-compose exec webui curl -s http://localhost:3000/api/health

# Kontrollera port binding
docker port $(docker-compose ps -q webui)

✅ WebUI Checklist:

• [ ] WebUI container körs utan restart loops
• [ ] Port 3000 är exponerad och tillgänglig
• [ ] Ollama är tillgänglig från WebUI container
• [ ] Database connection fungerar
• [ ] Inga JavaScript errors i browser console

🔧 WebUI Fix Commands:

# Restart WebUI
docker-compose restart webui

# Rebuild WebUI med fresh image
docker-compose up -d --build webui

# Testa connectivity till Ollama
docker-compose exec webui curl -s http://ollama:11434/api/tags

# Rensa browser cache och cookies
# (eller testa i incognito mode)

# Kontrollera WebUI environment
docker-compose exec webui env | grep -E "(WEBUI|OLLAMA)"

🌐 Problem: Authentication/Login issues

Symptom:

• Kan inte logga in med korrekta credentials
• "Unauthorized" errors
• Session expires omedelbart

Diagnostik:

# Kontrollera WebUI auth settings
docker-compose exec webui env | grep AUTH

# Kontrollera JWT settings
docker-compose exec webui env | grep JWT

# Kontrollera database user tables
docker-compose exec postgres psql -U postgres -d localai -c "SELECT * FROM users LIMIT 5;"

🔧 Auth Fix Commands:

# Reset admin user
docker-compose exec webui python -c "
from app.models.users import create_admin_user
create_admin_user('[email protected]', 'newpassword')
"

# Kontrollera JWT secret
grep JWT_SECRET_KEY .env

# Disable auth temporärt för troubleshooting
WEBUI_AUTH=false docker-compose up -d webui

# Reset session data
docker-compose exec webui rm -rf /app/sessions/*

D.2.4 n8n Workflow Troubleshooting

⚙️ Problem: n8n workflows körs inte

Symptom:

• Workflows går inte att aktivera
• Executions misslyckas
• Webhooks svarar inte

Diagnostik:

# Kontrollera n8n status
docker-compose ps n8n

# Kontrollera n8n logs
docker-compose logs n8n --tail=50

# Testa n8n API
docker-compose exec n8n curl -s http://localhost:5678/rest/active

# Kontrollera webhook URL
echo "Webhook URL: $WEBHOOK_URL"

✅ n8n Checklist:

• [ ] n8n container körs stabilt
• [ ] Database connection till n8n DB fungerar
• [ ] Webhook URL är korrekt konfigurerad
• [ ] External services (Ollama, APIs) är tillgängliga
• [ ] Credentials är korrekta

🔧 n8n Fix Commands:

# Restart n8n
docker-compose restart n8n

# Kontrollera n8n database
docker-compose exec n8n ls -la /home/node/.n8n/

# Reset n8n data (VARNING: raderar workflows)
docker-compose stop n8n
docker volume rm localai_n8n_data
docker-compose up -d n8n

# Testa från n8n container till Ollama
docker-compose exec n8n curl -s http://ollama:11434/api/tags

D.3 Performance Troubleshooting

D.3.1 System Resource Issues

🔥 Problem: High CPU Usage

Symptom:

• System känns långsamt
• Containers startar om sig själva
• Load average > antal CPU kärnor

Diagnostik:

# Kontrollera overall system load
top
htop  # om installerat

# Docker container stats
docker-compose ps -q | xargs docker stats --no-stream

# Kontrollera vilka processer som använder mest CPU
docker-compose exec ollama top

🔧 CPU Fixes:

# Minska Ollama parallelism
echo "OLLAMA_NUM_PARALLEL=1" >> .env
docker-compose up -d ollama

# Begränsa container CPU
# Lägg till i docker-compose.yml:
# cpus: "2.0"
# mem_limit: 4g

💾 Problem: Out of Memory

Symptom:

• Containers killed (OOMKilled)
• "out of memory" errors
• System freeze eller crash

Diagnostik:

# Kontrollera system memory
free -h

# Kontrollera swap usage
swapon --show

# Kontrollera memory per container
docker-compose ps -q | xargs docker stats --no-stream

# Kontrollera kernel messages för OOM
dmesg | grep -i "killed process"

🔧 Memory Fixes:

# Lägg till swap (4GB)
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Restart memory-hungry services
docker-compose restart ollama

# Använd mindre modell
docker-compose exec ollama ollama pull llama3.1:8b-instruct-q4_0

💿 Problem: Disk Space Issues

Symptom:

• "No space left on device"
• Containers kan inte starta
• Database writes misslyckas

Diagnostik:

# Kontrollera disk usage
df -h

# Kontrollera Docker disk usage
docker system df

# Kontrollera stora filer
du -sh /var/lib/docker/*
du -sh ./data/*

# Kontrollera logs
journalctl --disk-usage

🔧 Disk Space Fixes:

# Rensa Docker system
docker system prune -a

# Rensa gamla logs
sudo journalctl --vacuum-time=7d

# Rensa Ollama models som inte används
docker-compose exec ollama ollama list
docker-compose exec ollama ollama rm unused_model

# Flytta data till annan disk
sudo systemctl stop docker
sudo mv /var/lib/docker /mnt/new_disk/docker
sudo ln -s /mnt/new_disk/docker /var/lib/docker
sudo systemctl start docker

D.3.2 AI Model Performance Issues

🤖 Problem: Slow AI Responses

Symptom:

• AI tar >30 sekunder att svara
• Timeout errors
• Very low tokens/second

Diagnostik:

# Kontrollera GPU utilization
docker-compose exec ollama nvidia-smi

# Testa inference speed
time docker-compose exec ollama ollama run llama3.1:8b "Count to 10"

# Kontrollera VRAM usage
docker-compose exec ollama nvidia-smi --query-gpu=memory.used,memory.total --format=csv

# Kontrollera model loading
docker-compose exec ollama ollama ps

🔧 AI Performance Fixes:

# Force GPU usage
docker-compose exec ollama ollama run llama3.1:8b --gpu

# Använd kvantiserad modell
docker-compose exec ollama ollama pull llama3.1:8b-instruct-q4_0

# Rensa VRAM
docker-compose restart ollama

# Öka keep-alive för färre reloads
echo "OLLAMA_KEEP_ALIVE=30m" >> .env
docker-compose up -d ollama

D.4 Network och Connectivity Issues

D.4.1 Service Communication Problems

🌐 Problem: Services kan inte kommunicera

Symptom:

• "connection refused" mellan services
• API calls timeout
• DNS resolution fails

Diagnostik:

# Kontrollera Docker networks
docker network ls
docker network inspect localai_default

# Testa connectivity mellan containers
docker-compose exec webui ping ollama
docker-compose exec webui curl -s http://ollama:11434/api/tags

# Kontrollera DNS resolution
docker-compose exec webui nslookup ollama

✅ Network Checklist:

• [ ] Alla containers är i samma Docker network
• [ ] Services använder rätt hostnames (inte localhost)
• [ ] Portar är korrekta i .env filen
• [ ] Firewall blockerar inte internal traffic
• [ ] Docker daemon körs normalt

🔧 Network Fixes:

# Recreate network
docker-compose down
docker network prune
docker-compose up -d

# Kontrollera service hostnames i .env
grep -E "(HOST|URL)" .env

# Testa från host system
curl http://localhost:11434/api/tags
curl http://localhost:3000

D.4.2 External Access Problems

🔐 Problem: Kan inte nå services externt

Symptom:

• Services fungerar internt men inte från extern IP
• Timeout från internet
• SSL/TLS certificate errors

Diagnostik:

# Kontrollera port bindings
docker-compose ps
netstat -tlnp | grep -E "(3000|11434|5678)"

# Testa från annan maskin
curl -I http://your-server-ip:3000

# Kontrollera firewall
sudo ufw status
sudo iptables -L

🔧 External Access Fixes:

# Öppna portar i firewall
sudo ufw allow 3000
sudo ufw allow 11434

# Kontrollera bind address i .env
BIND_ADDRESS=0.0.0.0  # Not 127.0.0.1

# Lägg till reverse proxy (Nginx/Caddy)
# Se Kapitel 11 för detaljer

D.5 Security och Authentication Issues

D.5.1 Authentication Problems

🔐 Problem: Login fungerar inte

Symptom:

• Korrekta credentials avvisas
• "Invalid token" errors
• Session expires omedelbart

Diagnostik:

# Kontrollera auth environment
grep -E "(JWT|AUTH|PASSWORD)" .env

# Kontrollera user database
docker-compose exec postgres psql -U postgres -d localai -c "SELECT email, created_at FROM users;"

# Kontrollera JWT secret
echo "JWT Secret length: ${#JWT_SECRET_KEY}"

🔧 Auth Fixes:

# Reset JWT secret (VARNING: loggar ut alla users)
echo "JWT_SECRET_KEY=$(openssl rand -base64 32)" >> .env
docker-compose up -d

# Skapa ny admin user
docker-compose exec webui python manage.py create_admin [email protected] password123

# Disable auth temporärt
WEBUI_AUTH=false docker-compose up -d webui

D.6 Backup och Recovery Issues

D.6.1 Backup Problems

💾 Problem: Backup misslyckas

Symptom:

• Backup scripts returnerar errors
• Korrupta backup files
• Backup tar för lång tid

Diagnostik:

# Kontrollera disk space för backups
df -h /backup/location

# Testa backup manually
docker run --rm -v localai_postgres_data:/data -v $(pwd):/backup ubuntu tar -czf /backup/test.tar.gz -C /data .

# Kontrollera backup integrity
tar -tzf backup.tar.gz > /dev/null

🔧 Backup Fixes:

# Rensa gamla backups
find /backup/location -name "*.tar.gz" -mtime +30 -delete

# Backup med rätt permissions
sudo chown -R $(id -u):$(id -g) ./data/

# Scheduled backup med proper logging
0 2 * * * /path/to/backup_script.sh >> /var/log/backup.log 2>&1

D.7 Update och Migration Issues

D.7.1 Update Problems

🔄 Problem: Update misslyckas

Symptom:

• Containers startar inte efter update
• Database migration errors
• Incompatible versions

Diagnostik:

# Kontrollera image versions
docker-compose images

# Kontrollera migration logs
docker-compose logs --tail=50

# Rollback till förra versionen
git log --oneline
git checkout previous_working_commit

🔧 Update Fixes:

# Staged update process
1. Backup först
2. Test i development environment
3. Update med --no-deps för en service i taget
4. Validera efter varje steg

# Rollback procedure
docker-compose down
git checkout previous_version
docker-compose pull
docker-compose up -d

D.8 Emergency Procedures

D.8.1 Total System Failure

🚨 EMERGENCY: Hela systemet nere

Snabb Recovery Process:

Steg 1: Stop och assess (2 min)

docker-compose down
docker ps -a
docker system df

Steg 2: Basic recovery (5 min)

# Rensa problem containers
docker container prune -f

# Starta med basic services först
docker-compose up -d postgres
sleep 30
docker-compose up -d ollama
sleep 60
docker-compose up -d webui

Steg 3: Data recovery (10 min)

# Kontrollera data integrity
docker-compose exec postgres pg_isready
docker-compose exec postgres psql -U postgres -c "SELECT 1;"

# Restore från backup om nödvändigt
./scripts/restore_from_backup.sh latest

Steg 4: Validation (5 min)

# Testa alla services
curl http://localhost:3000
curl http://localhost:11434/api/tags
docker-compose exec postgres psql -U postgres -c "SELECT version();"

D.8.2 Data Corruption

💥 EMERGENCY: Data korrupt

Immediate Actions:

# 1. Stoppa alla write operations
docker-compose stop

# 2. Backup current state (även om korrupt)
sudo cp -r ./data ./data_corrupted_$(date +%Y%m%d_%H%M%S)

# 3. Restore från senaste kända bra backup
./scripts/restore_from_backup.sh 20240115_020000

# 4. Starta read-only för validation
docker-compose up -d --scale webui=0  # Bara database och Ollama

# 5. Validera data integrity
docker-compose exec postgres psql -U postgres -c "SELECT count(*) FROM users;"

# 6. Starta alla services om data är OK
docker-compose up -d

D.9 Monitoring och Prevention

D.9.1 Proactive Monitoring Setup

📊 Health Check Script (hälsokontroll var 5:e minut):

#!/bin/bash
# health_check.sh

LOG_FILE="/var/log/localai_health.log"
ALERT_EMAIL="[email protected]"

echo "$(date): Starting health check" >> $LOG_FILE

# Check services
if ! docker-compose ps | grep -q "Up"; then
    echo "ALERT: Services down" | mail -s "LocalAI Alert" $ALERT_EMAIL
fi

# Check disk space
DISK_USAGE=$(df / | awk 'NR==2 {print $5}' | cut -d'%' -f1)
if [ $DISK_USAGE -gt 85 ]; then
    echo "ALERT: Disk usage $DISK_USAGE%" | mail -s "LocalAI Disk Alert" $ALERT_EMAIL
fi

# Check memory
MEM_USAGE=$(free | grep Mem | awk '{printf("%.0f", $3/$2 * 100.0)}')
if [ $MEM_USAGE -gt 90 ]; then
    echo "ALERT: Memory usage $MEM_USAGE%" | mail -s "LocalAI Memory Alert" $ALERT_EMAIL
fi

# Check AI responsiveness
if ! timeout 30 docker-compose exec -T ollama ollama run llama3.1:8b "test" > /dev/null 2>&1; then
    echo "ALERT: AI not responding" | mail -s "LocalAI AI Alert" $ALERT_EMAIL
fi

echo "$(date): Health check completed" >> $LOG_FILE

📈 Performance Monitoring Script:

#!/bin/bash
# performance_monitor.sh

METRICS_FILE="/var/log/localai_metrics.log"

while true; do
    TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
    
    # Collect metrics
    CPU_USAGE=$(top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1)
    MEM_USAGE=$(free | grep Mem | awk '{printf("%.1f", $3/$2 * 100.0)}')
    DISK_USAGE=$(df / | awk 'NR==2 {print $5}' | cut -d'%' -f1)
    
    # Log metrics
    echo "$TIMESTAMP,CPU:$CPU_USAGE,MEM:$MEM_USAGE,DISK:$DISK_USAGE" >> $METRICS_FILE
    
    sleep 300  # 5 minutes
done

D.10 Troubleshooting Quick Reference

D.10.1 Command Quick Reference

🔧 Essential Commands:

# Service management
docker-compose ps                    # Status
docker-compose logs service_name     # Logs
docker-compose restart service_name  # Restart
docker-compose up -d --build        # Rebuild

# System diagnostics
docker system df                     # Disk usage
docker-compose ps -q | xargs docker stats  # Resource usage
free -h && df -h                    # System resources

# Database operations
docker-compose exec postgres psql -U postgres -d localai
docker-compose exec postgres pg_dump -U postgres localai > backup.sql

# Network troubleshooting
docker-compose exec webui ping ollama
docker-compose exec webui curl -s http://ollama:11434/api/tags

# Emergency procedures
docker-compose down && docker system prune -f && docker-compose up -d

D.10.2 Error Code Reference

D.10.3 Emergency Contact Information

📞 När du behöver hjälp:

Community Support:

• GitHub Issues: https://github.com/your-repo/issues
• Discord: https://discord.gg/localai-community
• Reddit: r/LocalAI

Professional Support:

• Enterprise Support: [email protected]
• Emergency Hotline: +46-xxx-xxx-xxx

Escalation Path:

1. Level 1: Community forums och documentation
2. Level 2: GitHub issues med logs och system info
3. Level 3: Professional support med remote access
4. Level 4: On-site support för kritiska miljöer

Detta troubleshooting appendix ger dig strukturerade metoder för att snabbt identifiera och lösa de vanligaste problemen i din lokala AI-infrastruktur. Kom ihåg att alltid börja med snabb diagnostik och dokumentera lösningar för framtida referens.