Skip to main content
This guide covers common issues you may encounter when deploying Lionz IPTV Downloader and their solutions.

​
General Troubleshooting Steps

Before diving into specific issues, try these general steps:
1

Check container status

docker-compose ps
Verify all services are running and healthy.
2

Review logs

docker-compose logs -f
Look for error messages in application, queue, and scheduler logs.
3

Verify environment configuration

docker-compose exec application php artisan config:show
Ensure all environment variables are set correctly.
4

Check service connectivity

docker-compose exec application ping host.docker.internal
Verify connection to host services (Aria2, Meilisearch).

​
Container Issues

Symptoms:
  • docker-compose up exits with errors
  • Containers show “Exited” status
Solutions:
  1. Check Docker logs:
docker-compose logs application
docker-compose logs queue
docker-compose logs scheduler
  1. Verify Docker has sufficient resources:
docker info | grep -i memory
Ensure at least 2GB RAM is available.
  1. Check for port conflicts:
# Check if port 8000 is already in use
lsof -i :8000
netstat -tuln | grep 8000
  1. Rebuild images from scratch:
docker-compose down -v
docker-compose build --no-cache
docker-compose up -d
Symptoms:
  • Container shows “Restarting” status
  • Health check fails continuously
Solutions:
  1. Check the entrypoint script execution:
docker-compose logs application | grep entrypoint
  1. Verify database initialization (docker/entrypoint.sh:8):
# Check if database file exists
ls -la ./data/database/
  1. Check migration failures:
docker-compose exec application php artisan migrate:status
  1. Verify APP_KEY is set:
docker-compose exec application php artisan key:generate
docker-compose restart application
  1. Check disk space:
df -h
docker system df
Symptoms:
  • Downloads stuck in pending state
  • Queue container running but idle
Solutions:
  1. Restart queue workers (docker/entrypoint.sh:26):
docker-compose exec queue php artisan queue:restart
docker-compose restart queue
  1. Check for failed jobs:
docker-compose exec application php artisan queue:failed
  1. Retry failed jobs:
docker-compose exec application php artisan queue:retry all
  1. Monitor queue in real-time:
docker-compose exec queue php artisan queue:monitor database
  1. Check memory limits (docker/Dockerfile:105):
docker stats queue
If memory usage approaches 2GB, the worker restarts automatically.

​
Database Issues

Symptoms:
  • “Permission denied” errors in logs
  • “Unable to open database file” errors
Solutions:
  1. Fix permissions on host:
sudo chown -R $USER:$USER ./data/database
chmod -R 755 ./data/database
  1. Ensure directory exists before container start:
mkdir -p ./data/database
touch ./data/database/database.sqlite
  1. Check container user (should be www-data):
docker-compose exec application whoami
  1. Recreate with correct permissions:
docker-compose down
rm -rf ./data/database/database.sqlite
docker-compose up -d
Symptoms:
  • Container starts but migrations fail
  • “Table already exists” errors
Solutions:
  1. Check migration status:
docker-compose exec application php artisan migrate:status
  1. Rollback and re-migrate:
docker-compose exec application php artisan migrate:rollback
docker-compose exec application php artisan migrate --force
  1. Fresh migration (DESTRUCTIVE - deletes all data):
docker-compose exec application php artisan migrate:fresh --force
  1. Check database connection:
docker-compose exec application php artisan db:show
Symptoms:
  • “Database is locked” errors
  • Timeouts during high concurrency
Solutions:SQLite has limited concurrency. For production:
  1. Enable WAL mode (better concurrency):
docker-compose exec application sqlite3 /data/database/database.sqlite "PRAGMA journal_mode=WAL;"
  1. Increase busy timeout:
// Add to config/database.php
'sqlite' => [
    'database' => env('DB_DATABASE'),
    'options' => [
        PDO::ATTR_TIMEOUT => 30,
    ],
],
  1. Consider migrating to PostgreSQL/MySQL for high-traffic deployments.

​
External Service Integration

Symptoms:
  • Downloads fail immediately
  • “Connection refused” to Aria2
Solutions:
  1. Verify Aria2 is running on host:
curl http://localhost:6800/jsonrpc
  1. Check host.docker.internal resolution:
docker-compose exec application ping host.docker.internal
  1. Update ARIA2_RPC_HOST in .env or docker-compose.yml:
# If Aria2 is on a different host
ARIA2_RPC_HOST=http://your-aria2-host:6800
  1. For Linux, add extra_hosts to docker-compose.yml:
application:
  extra_hosts:
    - "host.docker.internal:host-gateway"
  1. Test connection from container:
docker-compose exec application curl http://host.docker.internal:6800/jsonrpc
Symptoms:
  • Search not working
  • “Connection refused” to Meilisearch
  • Index sync failures
Solutions:
  1. Verify Meilisearch is running:
curl http://localhost:7700/health
  1. Check MEILISEARCH_HOST configuration (docker-compose.yml:13):
docker-compose exec application env | grep MEILISEARCH
  1. Sync indexes manually (docker/entrypoint.sh:52):
docker-compose exec application php artisan scout:sync-index-settings
  1. Re-index all data:
docker-compose exec application php artisan scout:flush "App\\Models\\Media"
docker-compose exec application php artisan scout:import "App\\Models\\Media"
  1. Verify master key if authentication is enabled:
# In .env
MEILISEARCH_KEY=your-master-key

​
Performance Issues

Symptoms:
  • Pages take >1 second to load
  • Timeouts under moderate load
Solutions:
  1. Verify caches are active (docker/entrypoint.sh:38-41):
docker-compose exec application php artisan optimize:status
  1. Rebuild caches:
docker-compose exec application php artisan optimize
  1. Check OPcache status:
docker-compose exec application php -i | grep opcache
  1. Monitor PHP-FPM/FrankenPHP workers:
docker-compose exec application php artisan octane:status
  1. Increase worker count if needed (edit docker/Dockerfile:112):
# Add --workers flag
CMD ["php", "artisan", "octane:frankenphp", "--workers=4", ...]
Symptoms:
  • Containers using >1GB RAM
  • Out of memory errors
Solutions:
  1. Check current memory usage:
docker stats --no-stream
  1. Review PHP memory limit (docker/Dockerfile:43):
memory_limit = 1024M
  1. Optimize queue worker memory (docker/Dockerfile:105):
# Workers restart after hitting limit
--memory=2048
  1. Clear application cache:
docker-compose exec application php artisan cache:clear
  1. Check for memory leaks in jobs:
docker-compose exec queue php artisan queue:work --once
# Monitor memory after each job
Symptoms:
  • Large downloads fail mid-stream
  • “Maximum execution time exceeded”
Solutions:
  1. Queue worker already has unlimited timeout (docker/Dockerfile:105):
--timeout=0
  1. Increase PHP max_execution_time if needed (docker/Dockerfile:41):
max_execution_time = 120
  1. Check Aria2 configuration:
# Ensure Aria2 has sufficient timeout settings
  1. Monitor job progress:
docker-compose logs -f queue

​
Build Issues

Symptoms:
  • Docker build fails during frontend stage
  • Vite errors in build logs
Solutions:
  1. Check Node/Bun version (docker/Dockerfile:3):
FROM oven/bun:1-alpine as frontend
  1. Clear Bun cache and rebuild:
docker-compose build --no-cache --pull frontend
  1. Verify package.json and bun.lock exist:
ls -la package.json bun.lock
  1. Build frontend locally to debug:
bun install
bun run build
  1. Check for missing environment variables (docker/Dockerfile:9-11):
ENV VITE_APP_NAME=$APP_NAME
ENV APP_ENV=$ENVIRONMENT
Symptoms:
  • Build fails during composer install
  • Missing PHP extensions
Solutions:
  1. Verify PHP version (docker/Dockerfile:16):
FROM dunglas/frankenphp:1.5.0-php8.4.5-bookworm
Ensure composer.json requires compatible PHP version.
  1. Check required extensions (docker/Dockerfile:19-35):
docker-compose exec application php -m
  1. Clear Composer cache:
docker-compose build --no-cache --build-arg COMPOSER_CLEAR_CACHE=1
  1. Check composer.json syntax:
composer validate

​
HTTPS/TLS Issues

Symptoms:
  • Cannot access site via HTTPS
  • Certificate errors
Solutions:
  1. Verify HTTPS ports are exposed (docker-compose.yml:46-47):
ports:
  - "443:443"
  - "443:443/udp"
  1. Check Caddyfile configuration (docker/Caddyfile):
docker-compose exec application cat /lionz/Caddyfile
  1. Ensure domain resolves to server:
nslookup your-domain.com
  1. Check Caddy logs:
docker-compose logs application | grep caddy
  1. Verify ports 80 and 443 are open:
sudo ufw status
sudo firewall-cmd --list-ports
Symptoms:
  • “Failed to obtain certificate” errors
  • ACME challenge failures
Solutions:
  1. Ensure port 80 is accessible (required for HTTP challenge):
curl -I http://your-domain.com
  1. Check DNS records:
dig your-domain.com
  1. Review Caddy’s ACME directory:
docker-compose exec application ls -la /data/caddy/certificates/
  1. Use staging certificates for testing:
{
  acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

​
Storage and Volumes

Symptoms:
  • Database resets after container restart
  • Uploads disappear
Solutions:
  1. Verify named volumes exist (docker-compose.yml:62-64):
docker volume ls | grep lionz
  1. Check volume mounts:
docker-compose config | grep volumes -A 5
  1. Don’t use docker-compose down -v unless intentional:
# This removes volumes:
docker-compose down -v  # DON'T DO THIS

# Use this instead:
docker-compose down
  1. Backup volumes before operations:
docker run --rm -v lionz_caddy_data:/data -v $(pwd):/backup alpine tar czf /backup/caddy_data.tar.gz /data

​
Getting Additional Help

If you continue to experience issues:
  1. Enable debug mode temporarily:
APP_DEBUG=true
LOG_LEVEL=debug
  1. Collect diagnostic information:
docker-compose ps
docker-compose logs --tail=500 > logs.txt
docker stats --no-stream > stats.txt
docker-compose exec application php artisan about > about.txt
  1. Check Laravel logs:
docker-compose exec application tail -f storage/logs/laravel.log
  1. Review system requirements:
    • Docker Engine 20.10+
    • Docker Compose v2.0+
    • Minimum 2GB RAM
    • Sufficient disk space for downloads
  2. Consult documentation:
  3. Report issues:

Build docs developers (and LLMs) love

Get started for freeTalk to us