> ## Documentation Index
> Fetch the complete documentation index at: https://developer.verilock.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for self-hosted deployments

## Diagnostic Commands

```bash theme={null}
# Check container status
docker compose ps

# View app logs (last 100 lines)
docker compose logs app --tail=100

# View all logs
docker compose logs -f

# Check license status
docker compose exec app php artisan license:heartbeat

# Check queue status
docker compose exec app php artisan horizon:status

# Run a health check
curl -f http://localhost:8080/up
```

## Common Issues

<AccordionGroup>
  <Accordion title="Container keeps restarting">
    Check the logs:

    ```bash theme={null}
    docker compose logs app --tail=50
    ```

    **Common causes:**

    * `APP_KEY` not set → The entrypoint generates it automatically. If it persists, run:
      ```bash theme={null}
      docker compose exec app php artisan key:generate --force
      ```
    * Database not ready → Ensure PostgreSQL is healthy:
      ```bash theme={null}
      docker compose ps postgres
      ```
    * Permission issues → Fix storage permissions:
      ```bash theme={null}
      docker compose exec app chown -R www-data:www-data storage bootstrap/cache
      ```
  </Accordion>

  <Accordion title="License validation failed">
    ```
    License server unreachable and grace period expired.
    ```

    **Solutions:**

    1. Check outbound connectivity to `license.verilock.com`:
       ```bash theme={null}
       docker compose exec app curl -I https://license.verilock.com
       ```
    2. Verify your license key in `.env`:
       ```bash theme={null}
       grep VERILOCK_LICENSE_KEY .env
       ```
    3. If behind a corporate proxy, configure Docker proxy settings.
    4. Grace period is 7 days by default. If the server was unreachable for longer, restore connectivity.
  </Accordion>

  <Accordion title="Database connection refused">
    ```
    SQLSTATE[08006] Connection refused
    ```

    Ensure PostgreSQL is running:

    ```bash theme={null}
    docker compose ps postgres
    docker compose logs postgres --tail=20
    ```

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

    * `DB_HOST` should be `postgres` (Docker service name)
    * `DB_PASSWORD` must match `POSTGRES_PASSWORD`
  </Accordion>

  <Accordion title="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:**

    ```nginx theme={null}
    client_max_body_size 50M;
    ```

    **Caddy:**

    ```
    kyc.your-domain.com {
        request_body {
            max_size 50MB
        }
        reverse_proxy app:80
    }
    ```
  </Accordion>

  <Accordion title="Queue jobs not processing">
    Horizon manages queue workers. Check its status:

    ```bash theme={null}
    docker compose exec app php artisan horizon:status
    ```

    If Horizon is paused:

    ```bash theme={null}
    docker compose exec app php artisan horizon:continue
    ```

    Check failed jobs:

    ```bash theme={null}
    docker compose exec app php artisan queue:failed
    ```

    Retry failed jobs:

    ```bash theme={null}
    docker compose exec app php artisan queue:retry all
    ```
  </Accordion>

  <Accordion title="MinIO / Storage errors">
    Check MinIO is healthy:

    ```bash theme={null}
    docker compose ps minio
    docker compose logs minio --tail=20
    ```

    Verify the bucket exists:

    ```bash theme={null}
    docker compose exec minio mc ls local/
    ```

    If the bucket is missing, recreate it:

    ```bash theme={null}
    docker compose restart minio-init
    ```
  </Accordion>

  <Accordion title="AML screening returns no results">
    The AML engine needs time to download and index sanctions data on first start (\~5-10 minutes).

    Check status:

    ```bash theme={null}
    docker compose logs aml-engine --tail=30
    ```

    Force a data refresh:

    ```bash theme={null}
    docker compose restart aml-engine
    ```
  </Accordion>

  <Accordion title="Slow performance">
    **Quick wins:**

    1. Ensure Redis is used for cache/session (not `database`):
       ```env theme={null}
       CACHE_STORE=redis
       SESSION_DRIVER=redis
       ```
    2. Check available memory:
       ```bash theme={null}
       docker stats --no-stream
       ```
    3. Increase PHP-FPM workers if CPU is available (edit `docker/php-fpm.conf`).
    4. Ensure OPcache is enabled (it is by default).
  </Accordion>
</AccordionGroup>

## Logs

| Log         | Location                     | Description                 |
| ----------- | ---------------------------- | --------------------------- |
| Application | `storage/logs/laravel.log`   | Main application log        |
| Horizon     | `storage/logs/horizon.log`   | Queue worker log            |
| Scheduler   | `storage/logs/scheduler.log` | Cron scheduler log          |
| Nginx       | Docker stdout                | Web server access/error log |
| PostgreSQL  | Docker stdout                | Database log                |

View any log:

```bash theme={null}
# App log
docker compose exec app tail -f storage/logs/laravel.log

# All Docker logs
docker compose logs -f
```

## Support

If you can't resolve an issue:

1. Collect diagnostics:
   ```bash theme={null}
   docker compose exec app php artisan about > diagnostics.txt
   docker compose ps >> diagnostics.txt
   docker compose logs app --tail=200 >> diagnostics.txt
   ```
2. Email `support@verilock.com` with the diagnostics file and a description of the issue.
3. Enterprise customers can use their dedicated support channel.