Back to Docs
Troubleshooting
Common issues and their solutions. Can't find what you need? Contact support.
Quick Diagnostics
# Check all services
docker-compose ps
# View recent logs
docker-compose logs --tail=50
# Check resource usage
docker stats
# Test API health
curl http://localhost:8000/health
# Test database connection
docker exec aelira-backend python -c "from src.db import engine; print('OK')"
# Test Ollama
curl http://localhost:11434/api/tagsCommon Issues
Ollama not responding
AI features return errors, alt text generation fails
Solutions:
Check if Ollama is running: docker-compose psView Ollama logs: docker-compose logs ollamaVerify models are downloaded: docker exec aelira-ollama ollama listPull models manually: docker exec aelira-ollama ollama pull llama3.2:3b
Database connection failed
API returns 500 errors, scans don't save
Solutions:
Check PostgreSQL is running: docker-compose ps postgresVerify DATABASE_URL in .env is correctCheck PostgreSQL logs: docker-compose logs postgresTest connection: docker exec aelira-postgres psql -U aelira -c "SELECT 1"
Out of memory
Containers crash, scans timeout, system becomes unresponsive
Solutions:
Increase Docker memory limit (16GB recommended)Use smaller AI models: OLLAMA_MODEL=llama3.2:1bReduce concurrent workers in configurationMonitor memory: docker stats
PDF OCR not working
Scanned PDFs return no text, OCR errors
Solutions:
Verify Tesseract is installed in containerCheck PDF is actually an image-based scanTry with ocr=true parameter explicitlyCheck backend logs for Tesseract errors
Website scan timeout
Web scans never complete, timeout errors
Solutions:
Increase timeout in configurationCheck if target site is accessible from serverReduce max_pages for crawlingCheck Playwright browser: docker exec aelira-backend playwright install
Port already in use
Docker containers fail to start
Solutions:
Check what's using the port: lsof -i :8000Change ports in docker-compose.ymlStop conflicting servicesUse different port mappings: 8001:8000
LaTeX conversion fails
Math equations return errors, MathML not generated
Solutions:
Check LaTeX syntax is validEscape backslashes properly in JSON: \\frac not \fracVerify latex2mathml is installedCheck backend logs for specific errors
Dashboard won't load
Blank page, JavaScript errors in console
Solutions:
Check dashboard container is runningVerify VITE_API_URL is correctClear browser cache and reloadCheck dashboard logs: docker-compose logs dashboard
Getting Help
GitHub Issues (Q2 2026)
Report bugs and request features — coming with open source release
Email Support
Priority support for pilot users
Before Reporting an Issue
Please include the following in your bug report:
- - Output of
docker-compose ps - - Relevant logs from
docker-compose logs - - Your .env configuration (without secrets)
- - Steps to reproduce the issue
- - Expected vs actual behavior