Maintenance
Troubleshooting
Fixes for the problems people meet most.
| Problem | Cause and fix |
|---|---|
| Installer says a folder is not writable | Set storage and bootstrap/cache to permission 775 and make sure the web user owns them. |
| White page or “500 Server Error” | Open the newest file in storage/logs. The first lines name the exact problem. Common causes: a missing PHP extension, wrong folder permissions, or a wrong database password in .env. |
| Page looks unstyled | The document root must be the public folder. Clear the browser cache. |
| Scheduled tasks, reminders or update notices do not run | Check that the every-minute cron job exists and uses PHP 8.2. See Installation. The scheduler status is on Settings → System configuration. |
| “Check for updates” shows an error | Confirm the server can reach the licence server, then press Verify now. |
| Update readiness shows a red line | Fix that item (sodium, zip, write permission or disk space), then check again. |
| Licence says another domain | Move the licence from the activation screen or Move to another domain. |
| Locked out after wrong passwords | Wait the number of minutes shown. Limits reset by themselves. |
| Password reset email does not arrive | Check Settings → Mail and use Send test e-mail. Check the spam folder. The link works for 60 minutes and only the newest one is valid. Check storage/logs for a mail error. |
| A webhook shows “Blocked” | The address points at this server or a private network. Use a public address, or set QOREX_ALLOW_PRIVATE_URLS=true if it is intentional. |
| Emails are not sent | Check Settings → Mail and use Send test e-mail. |
| SMS or payment-link text is not sent | Switch on a gateway under Settings → SMS. |
| Receipt will not print | Check Settings → Printers, use Test connection, and review Print logs. For silent printing make sure the Print Agent is connected. |
| POS says add a warehouse | Create a warehouse first. See Warehouses & stock control. |
| A menu item is missing | Check your role's permissions and that the module is switched on under Settings → Modules. |
| Cannot delete a unit, category or warehouse | It is in use. Deactivate it instead, or remove what uses it. |
| Stock looks wrong after deleting a sale or damage record | Deleting does not restore stock. Use a return, or record a stock adjustment. |
| Changes to files do not show | Run php artisan optimize:clear over SSH. |
| Gateway payments stay pending | Your site must use HTTPS and be reachable so the gateway can confirm. Pending links are re-checked on a schedule. |
Reading the log#
Errors are written to a daily file such as storage/logs/laravel-YYYY-MM-DD.log. Send the first few lines of the newest error to support. They show the cause and the file involved. Keep APP_DEBUG set to false on a live site.