Zum Inhalt

Common Issues & Troubleshooting

Docker Issues

Port Already in Use

Problem: Bind for 0.0.0.0:8000 failed: port is already allocated

Solution: 

# Find process using port
lsof -i :8000

# Kill process
lsof -ti:8000 | xargs kill -9

# Or change port in docker-compose.yml
ports:
  - "8001:8000"  # Map to different host port

Container Won't Start

Problem: Container exits immediately

Solution: 

# Check logs
docker compose logs backend

# Check health
docker compose ps

# Rebuild without cache
docker compose build --no-cache backend
docker compose up -d

Out of Disk Space

Problem: no space left on device

Solution: 

# Check Docker disk usage
docker system df

# Clean up
docker system prune -a --volumes

# Remove old images
docker images | grep solarlog | awk '{print $3}' | xargs docker rmi

# Check system disk
df -h /

Database Issues

Connection Refused

Problem: could not connect to server: Connection refused

Solution: 

# Check if PostgreSQL is running
docker compose ps postgres

# Check PostgreSQL logs
docker compose logs postgres

# Restart PostgreSQL
docker compose restart postgres

# Verify connection
docker compose exec postgres pg_isready

Migration Failed

Problem: alembic upgrade head fails

Solution: 

# Check current migration
docker compose exec backend alembic current

# Downgrade one step
docker compose exec backend alembic downgrade -1

# Upgrade again
docker compose exec backend alembic upgrade head

# If still fails, reset database
docker compose down -v
docker compose up -d
docker compose exec backend alembic upgrade head

Database Locked

Problem: database is locked (SQLite only)

Solution: 

# Use PostgreSQL in production instead of SQLite

# Or increase timeout
# database.py
engine = create_engine(
    "sqlite:///./data/solarlog.db",
    connect_args={"timeout": 30}
)

Backend Issues

ModuleNotFoundError

Problem: ModuleNotFoundError: No module named 'app'

Solution: 

# Check Python path
docker compose exec backend python -c "import sys; print(sys.path)"

# Reinstall dependencies
docker compose exec backend pip install -r requirements.txt

# Rebuild container
docker compose build --no-cache backend

Import Errors

Problem: ImportError: cannot import name 'X' from 'Y'

Solution: 

# Check for circular imports
grep -r "from app" backend/app/

# Verify __init__.py files exist
find backend/app -type d -exec ls {}/__init__.py \;

# Clear Python cache
find backend -type d -name __pycache__ -exec rm -rf {} +
find backend -type f -name "*.pyc" -delete

Scheduler Not Running

Problem: Inverter polling doesn't start

Solution: 

# Check logs
docker compose logs backend | grep scheduler

# Verify enabled inverters
docker compose exec backend python -c "
from app.database.session import SessionLocal
from app.database.models import Inverter
db = SessionLocal()
inverters = db.query(Inverter).filter_by(enabled=True).all()
print(f'Enabled inverters: {len(inverters)}')
"

# Restart backend
docker compose restart backend

Frontend Issues

White Screen (Production Build)

Problem: Frontend shows blank page

Solution: 

# Check browser console for errors
# Usually missing environment variables

# Verify build
docker compose exec frontend ls -la /usr/share/nginx/html

# Check Nginx logs
docker compose logs frontend

# Rebuild frontend
docker compose build --no-cache frontend
docker compose up -d frontend

API Calls Fail (CORS)

Problem: blocked by CORS policy

Solution: 

# backend/app/main.py
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:3000",
        "https://solarlog.karma.organic"
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Material-UI Errors

Problem: TypeError: Cannot read property 'item' of undefined

Solution: 

# Verify Material-UI version (must be v6)
cd frontend-web
npm list @mui/material

# If v7, downgrade
npm install @mui/material@^6.0.0 @mui/icons-material@^6.0.0

# Clear cache and rebuild
rm -rf node_modules package-lock.json
npm install

Network Issues

DNS Resolution Failed

Problem: Could not resolve host: solarlog-api.karma.organic

Solution: 

# Check DNS
nslookup solarlog-api.karma.organic
dig solarlog-api.karma.organic

# Wait for DNS propagation (5-10 minutes)

# Check Cloudflare DNS settings
# Verify CNAME records exist

Cloudflare Tunnel 404

Problem: HTTP ERROR 404 on Cloudflare domain

Solution: 

# Check tunnel status
cloudflared tunnel list

# Verify tunnel is running
cloudflared tunnel info solarlog-tunnel

# Check ingress rules
cat deployment/cloudflare/tunnel-config.yml

# Verify local services are running
curl http://localhost:3000
curl http://localhost:8000/health

# Restart tunnel
cloudflared tunnel --config deployment/cloudflare/tunnel-config.yml run solarlog-tunnel

# Check tunnel logs
cloudflared tunnel --config deployment/cloudflare/tunnel-config.yml --loglevel debug run solarlog-tunnel

Can't Connect to Inverter

Problem: Connection timeout when polling inverter

Solution: 

# Check network connectivity
ping 192.168.1.100  # inverter IP

# Test Modbus TCP
nc -zv 192.168.1.100 502

# Check firewall
sudo ufw status

# Verify inverter configuration
docker compose exec backend python -c "
from app.database.session import SessionLocal
from app.database.models import Inverter
db = SessionLocal()
inv = db.query(Inverter).first()
print(f'IP: {inv.ip_address}, Port: {inv.port}')
"

Performance Issues

High CPU Usage

Problem: Backend consumes 100% CPU

Solution: 

# Check active processes
docker stats

# Reduce polling frequency
# In .env
POLL_INTERVAL=120  # Increase from 60 to 120 seconds

# Add resource limits
# docker-compose.yml
services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G

High Memory Usage

Problem: Container uses too much memory

Solution: 

# Check memory usage
docker stats --no-stream

# Add memory limits
# docker-compose.yml
services:
  backend:
    deploy:
      resources:
        limits:
          memory: 512M

# Clear logs
docker compose logs --tail=0 backend > /dev/null

Slow Database Queries

Problem: API responses are slow

Solution: 

-- Add indexes
CREATE INDEX idx_production_data_inverter_timestamp 
ON production_data(inverter_id, timestamp DESC);

CREATE INDEX idx_production_data_timestamp 
ON production_data(timestamp DESC);

-- Vacuum database
VACUUM ANALYZE;

Cloudflare Issues

Tunnel Won't Start

Problem: error="failed to start tunnel"

Solution: 

# Check credentials file
ls -la ~/.cloudflared/*.json

# Re-login
cloudflared tunnel login

# Verify tunnel exists
cloudflared tunnel list

# Recreate tunnel if needed
cloudflared tunnel delete solarlog-tunnel
cloudflared tunnel create solarlog-tunnel
cloudflared tunnel route dns solarlog-tunnel solarlog.karma.organic

SSL Certificate Error

Problem: certificate verify failed

Solution: 

# tunnel-config.yml
ingress:
  - hostname: solarlog.karma.organic
    service: http://localhost:3000
    originRequest:
      noTLSVerify: true  # For local HTTP services

Logging & Debugging

Enable Debug Logging

# Backend
# .env
DEBUG=true
LOG_LEVEL=DEBUG

# Frontend (browser console)
localStorage.debug = '*'

# Docker
docker compose --verbose up

# Cloudflare Tunnel
cloudflared tunnel --loglevel debug run solarlog-tunnel

Common Log Locations

# Docker logs
docker compose logs -f --tail=100

# Backend logs
docker compose logs backend

# Nginx logs
docker compose exec nginx cat /var/log/nginx/access.log
docker compose exec nginx cat /var/log/nginx/error.log

# System logs
tail -f /var/log/syslog
journalctl -u docker -f

Emergency Procedures

Complete Reset

# WARNING: This deletes all data!

# Stop everything
docker compose down -v

# Remove images
docker rmi $(docker images | grep solarlog | awk '{print $3}')

# Clean system
docker system prune -a --volumes

# Rebuild
docker compose build
docker compose up -d

# Verify
docker compose ps
curl http://localhost:8000/health

Restore from Backup

# Stop services
docker compose down

# Restore database
gunzip -c /backups/solarlog_backup_20250123.sql.gz | \
  docker compose exec -T postgres psql -U solarlog solarlog

# Start services
docker compose up -d

# Verify data
docker compose exec backend python -c "
from app.database.session import SessionLocal
from app.database.models import Inverter
db = SessionLocal()
print(f'Inverters: {db.query(Inverter).count()}')
"

Getting Help

If none of these solutions work:

  1. Check full logs: docker compose logs > debug.log
  2. Check system resources: docker stats
  3. Review configuration: cat docker-compose.yml .env
  4. Create GitHub Issue with:
  5. Error message
  6. docker-compose.yml
  7. Relevant logs
  8. Steps to reproduce

Useful Commands

# Complete diagnostic
docker compose ps
docker compose logs --tail=50
docker stats --no-stream
df -h /
free -h
curl http://localhost:8000/health
curl -I http://localhost:3000

# Quick restart
docker compose restart

# Nuclear option (full rebuild)
docker compose down -v && \
docker compose build --no-cache && \
docker compose up -d