Troubleshooting

Container keeps restarting

Check the logs:

docker compose logs app --tail=50

Common causes:

APP_KEY not set → The entrypoint generates it automatically. If it persists, run:
docker compose exec app php artisan key:generate --force
Database not ready → Ensure PostgreSQL is healthy:
docker compose ps postgres

Permission issues → Fix storage permissions:

docker compose exec app chown -R www-data:www-data storage bootstrap/cache

License validation failed

License server unreachable and grace period expired.

Solutions:

Check outbound connectivity to license.verilock.com:

docker compose exec app curl -I https://license.verilock.com

Verify your license key in .env:
grep VERILOCK_LICENSE_KEY .env
If behind a corporate proxy, configure Docker proxy settings.
Grace period is 7 days by default. If the server was unreachable for longer, restore connectivity.

Database connection refused

SQLSTATE[08006] Connection refused

Ensure PostgreSQL is running:

docker compose ps postgres
docker compose logs postgres --tail=20

Check credentials match between .env and docker-compose.yml:

File upload fails (413 error)

The default upload limit is 50MB. If you’re behind an additional reverse proxy, ensure it also allows large uploads:Nginx:

client_max_body_size 50M;

Caddy:

kyc.your-domain.com {
    request_body {
        max_size 50MB
    }
    reverse_proxy app:80
}

Queue jobs not processing

Horizon manages queue workers. Check its status:

docker compose exec app php artisan horizon:status

If Horizon is paused:

docker compose exec app php artisan horizon:continue

Check failed jobs:

docker compose exec app php artisan queue:failed

Retry failed jobs:

docker compose exec app php artisan queue:retry all

MinIO / Storage errors

Check MinIO is healthy:

docker compose ps minio
docker compose logs minio --tail=20

Verify the bucket exists:

docker compose exec minio mc ls local/

If the bucket is missing, recreate it:

docker compose restart minio-init

AML screening returns no results

The AML engine needs time to download and index sanctions data on first start (~5-10 minutes).Check status:

docker compose logs aml-engine --tail=30

Force a data refresh:

docker compose restart aml-engine

Slow performance

Quick wins:

Ensure Redis is used for cache/session (not database):
CACHE_STORE=redis SESSION_DRIVER=redis
Check available memory:
docker stats --no-stream
Increase PHP-FPM workers if CPU is available (edit docker/php-fpm.conf).
Ensure OPcache is enabled (it is by default).

Diagnostic Commands