Merchant & operations
Troubleshooting a merchant installation
Diagnose installation, routing, background work, payment, package, and backup failures without destructive shortcuts.
On this page
Start with evidence and contain the impact
Record what failed, when it began, which application/package revision is deployed, and whether a recent configuration or migration change preceded it. Restrict checkout if payment or delivery state is uncertain. Keep a copy of relevant logs privately and remove customer details, keys, cookies, and authorization headers before sharing an excerpt.
Run from the application root with the intended PHP runtime:
php artisan agovena:doctor
composer check-platform-reqs --no-dev
The doctor command distinguishes required failures from warnings. It can exit successfully while warning about mail, failed jobs, HTTPS, missing assets, or persistence. A successful exit is not permission to ignore those warnings. Requirements checks may also attempt to create the public storage link, so doctor is not strictly read-only.
Installation and schema problems
| Symptom | Check and next action |
|---|---|
| Missing PHP extension | Compare CLI and FPM runtimes and enable the extension in the correct one. Do not ignore Composer platform requirements. |
| Cannot connect to the database | Check the configured host, database, account permissions, and whether stale cached configuration is in use. Do not print the password. |
| Installer reports pending migrations | Apply the prepared schema step in installation, or use the backed-up upgrade procedure for an existing store. |
| Installer says already installed | Use normal login. Do not delete the marker or installed settings to create another owner. |
| Installation restore warning | Restore matching database and storage/app/agovena/installed.json; investigate a mismatched recovery point. |
Missing vendor or asset manifest |
Deploy the correct artifact or install locked dependencies/build assets for a source checkout. Do not remove checks to conceal missing files. |
A migration error can leave partially applied schema. Keep the store restricted and diagnose the first failure. Never use migrate:fresh to repair a live store.
Web and media problems
502: check the running FPM service, actual socket name, and access permissions. The dedicated pool uses a different socket from the default Nginx template. See Nginx.
Homepage works, other routes 404: check the public/ document root, Nginx try_files, or Apache rewrite/override configuration. See Apache.
PHP is downloaded or source is visible: stop public access immediately. Repair the PHP handler and inspect what was exposed before reopening.
Images missing: confirm the underlying public files exist and run php artisan storage:link if the link is missing. Private files must remain private.
Upload rejected: distinguish proxy/web-server request limits, PHP POST/upload limits, Livewire validation, and product/package-specific limits. Raising only one may have no effect.
Login or callback redirects are wrong: review APP_URL, HTTPS termination, trusted proxies, and session persistence. Do not disable CSRF or two-factor controls as a workaround.
Email and background work
If mail does not arrive, check MAIL_MAILER: log is not delivery. Review the actual SMTP connection settings, sender authorization, Admin → Email log, and Failed jobs. Provider rejection, worker failure, and spam filtering need different fixes.
For background work:
sudo systemctl status agovena-queue.service
php artisan schedule:list
Check the scheduler heartbeat in Admin and verify a real queued operation. A heartbeat does not prove worker consumption. A running worker can still use the wrong queue connection or old cached configuration. After a deliberate configuration fix, clear configuration and restart workers through the operating procedure.
Retry only selected failed jobs after correcting the cause. Check the remote result first for payment/provisioning jobs. Do not empty failure records to create a clean dashboard.
Provider and package failures
Run php artisan agovena:verify-providers for enabled connection checks. If no health callback exists, its warning is not a provider success. For a paid-at-provider/pending-in-store mismatch, check webhook reachability and signature/account configuration before requesting another payment. Follow payments.
For package errors, check compatibility, dependencies, available disk space, write access to storage/app/packages, Composer availability, outbound HTTPS, and the configured journal connection. Do not hand-edit package flags or delete the package Composer directory. See package recovery.
Backup errors and escalation
An unreadable backup may indicate the wrong APP_KEY, corruption, or missing storage. A database-client failure may mean the dump/restore executable is absent or permissions are insufficient. A verification success does not prove full restoration. Use backup and restore, never an untested live restore to diagnose an artifact.
Escalate with the failing command/action, sanitized first error, versions, database driver, web server, queue backend, and steps already attempted. Share neither .env nor a full database dump publicly. Security concerns belong in the private process described by SECURITY.md.