Troubleshooting
| Area | Symptom | Check / fix |
|---|---|---|
| Login | "Invalid email or password" | Caps lock and email address. The account locks after 5 failures for 15 minutes; an admin can unlock it under Users |
| Login | No password reset email | Check spam. Email may not be configured; an admin can reset the password under Users |
| Login | 2FA code rejected | Set the phone time to automatic |
| Session | Signed out | Idle timeout (Settings → Security). Password changes sign out other devices |
| Session | "Security token expired" (419) | Refresh the page; the form was open too long |
| Camera | Camera does not start | HTTPS required; allow camera permission (see docs/mobile-scanning.md); close other camera apps |
| Camera | Barcode not read | Use the Light button, hold 10–20 cm away, avoid glare; type the code manually |
| Scanner | Wrong characters | Match the scanner keyboard language to the device |
| Scanner | GS1 batch/expiry missing | Enable FNC1→GS or AIM IDs on the scanner |
| Scan | "Not recognised" | Check the working warehouse; add the barcode to the product (alternate barcodes) |
| Printing | Labels misaligned | Print dialog: correct paper/label size, margins None, scale 100%, no headers/footers |
| Printing | Want silent printing | Browsers cannot print silently; see docs/barcode-and-printers.md |
| CSV | Errors on import | Download the error report; see docs/csv-import.md |
| CSV | Garbled accents | Save as CSV UTF-8 |
| Database | Error page with reference code | Check credentials in config/config.php and the hPanel MySQL status; see storage/logs for the reference |
| Test email fails | Host, port and encryption (587/TLS or 465/SSL), credentials, From address; check the email log | |
| Data | Not refreshing | Tab hidden pauses polling; press refresh; check the offline banner |
| PWA | Old version showing | Press "Update now", or close all tabs and reopen |
| PWA | Install option missing | HTTPS plus Chrome/Edge, or Safari "Add to Home Screen" |
| Permissions | 403 "You do not have permission" | Role lacks the action, or the warehouse is not assigned |
| Stock | "Insufficient stock" | Stock is reserved for orders or held in another status/bin; check Inventory → Stock |
| Stock | Expired batch cannot be dispatched | By design. Write it off with an adjustment (Expired stock write-off) |
| Backup | Backup fails | Disk space and the PHP time limit; see docs/backup-restore.md |
| Restore | Restore failed part-way | Restore the automatic pre-restore backup listed under Backups |
| Cron | Scheduled reports not sent | Cron job path and command; Email & Schedules shows the last cron run |
Logs: storage/logs/app-YYYY-MM.log (via hPanel File Manager; not web-accessible). Errors shown to users carry a reference code that matches the log entry.