# Troubleshooting

## “Setup required” appears

The public front controller displays this when the application cannot bootstrap.

Check:

1. `/home/CPANEL_USER/vulaprize-app/` exists beside `public_html`.
2. If this is a fresh install, open `/setup.php` and finish the one-time setup.
3. Use the full cPanel database name and username, including the account prefix.
4. The database user has been assigned to the database with **ALL PRIVILEGES**.
5. The host has PHP 8.3+ and the `pdo_mysql` extension enabled.
6. After setup succeeds, remove `public_html/setup.php`.

## “Access denied for user”

The MySQL username/password is wrong or the user has not been assigned to the database. Re-add it in **MySQL Databases → Add User To Database**.

## “Table ... doesn't exist”

Open `/setup.php` and use an empty dedicated database for a fresh install. The installer imports the schema automatically. If the database contains only part of the schema, use a new empty database or follow the documented recovery process; the installer will not drop existing tables.

## Login always fails

- Confirm the admin was created using `bin/create-admin.php`.
- Confirm user status is `active`.
- Confirm email spelling and case.
- After repeated attempts, wait one hour or clear appropriate `login_attempts` rows through phpMyAdmin only during controlled testing.

## All routes except `/` return 404

- Confirm `public_html/.htaccess` was uploaded.
- Confirm Apache rewrite support is enabled.
- Check whether the host disables `.htaccess` overrides.
- For a subdirectory installation, configure `APP_BASE_PATH=/subdirectory` and adjust the front-controller placement.

## Images do not upload

- Enable `fileinfo`.
- Check `upload_max_filesize` and `post_max_size`.
- Ensure `vulaprize-app/storage/uploads/contests` and `public_html/media/contest-public` are writable by PHP.
- Accepted MIME types are JPEG, PNG and WebP.

## Session logs out immediately

- Confirm `storage/sessions` is writable.
- Ensure `SESSION_SECURE_COOKIE=false` only during local non-HTTPS testing; use `true` on the live HTTPS domain.
- Confirm `APP_BASE_PATH` is correct.

## PayFast return page says pending

This is expected until a verified ITN is processed. Check:

- Public HTTPS ITN URL is reachable.
- PayFast passphrase matches.
- Merchant ID/key are correct for sandbox or live mode.
- `curl` is enabled.
- The remote validation URL matches the mode.
- Admin → Orders → Order Details shows the payment event and verification flags.
- `storage/logs` contains no processing error.

Never mark an order paid merely because the browser returned from PayFast.

## Duplicate payment callbacks

The system stores unique payment events and checks for an existing `paid_order` entitlement before granting. Inspect the order and payment event in admin. Do not manually insert an additional entitlement.

## Email remains pending

- Add the email cron job.
- Check Admin → Email Queue.
- Configure SMTP or confirm PHP `mail()` works.
- Install Composer dependencies when using PHPMailer SMTP.
- Check `storage/logs` and the queue's `last_error`.

## Cron jobs show no heartbeat

Run one manually through cPanel Terminal:

```bash
/opt/cpanel/ea-php83/root/usr/bin/php -q /home/CPANEL_USER/vulaprize-app/cron/close-contests.php
```

Then check Admin → System Health.

## Correct answer cannot be decrypted

The most common cause is a changed `APP_KEY`. Restore the original key from the secure backup. There is no safe recovery without it.

## Blank page or HTTP 500

- Set `APP_DEBUG=true` temporarily only on staging.
- Check `vulaprize-app/storage/logs/app-YYYY-MM-DD.log`.
- Run `php bin/check-install.php`.
- Run PHP lint from Terminal:

```bash
find /home/CPANEL_USER/vulaprize-app -name '*.php' -print0 | xargs -0 -n1 php -l
```

Return `APP_DEBUG=false` before production.