# Troubleshooting Guide

## Blank page / HTTP 500

1. Check PHP error logs.
2. Run `php -l` on changed files.
3. Confirm PHP version is 8.0+.
4. Confirm required extensions: `pdo_mysql`, `mbstring`, `json`, `session`.

## Routes return 404

1. Confirm `.htaccess` uploaded.
2. Confirm Apache `mod_rewrite` is enabled.
3. Confirm files are not nested in an extra folder.
4. For PHP built-in server, use `dev-router.php`.

## Database connection error

1. Check `app/config.php` database host/name/user/password.
2. Confirm DB user has privileges.
3. Confirm database exists.
4. Confirm MySQL/MariaDB service is running.

## Installer will not run

If `install.lock` exists, installer is intentionally locked.

For a disposable reinstall only:

```text
/install.php?force=reinstall
```

Do not do this against production data without backups.

## Uploads fail

1. Confirm upload folder exists.
2. Confirm PHP/web user can write to upload folder.
3. Confirm upload file size is within module limit.
4. Confirm file extension is allowed.

## Accountant ZIP export fails

The ZIP export requires PHP `ZipArchive`. If unavailable, use JSON or CSV export.

## Cold-chain import creates out-of-range alerts

This is expected if:

- `alarm` column is `yes` or `1`
- min temperature is below 2°C
- max temperature is above 8°C

Review Temperature Logs and raise a Deviation if required.
