SupportHubCX Platform Docs
CtrlK
v1.0.0 Public Support Open App
Docs/Maintenance & Troubleshooting

Maintenance & Troubleshooting

Most operational issues fall into a few groups: cache, permissions, queue worker, scheduler, mail delivery, storage links, installer lock, database credentials, or role permissions.

Safe Maintenance Commands

php artisan optimize:clear
php artisan storage:link
php artisan queue:restart
php artisan tickets:sync-intelligence --open-only

Blank Page or 500 Error

  • Check storage/logs/laravel.log.
  • Run php artisan optimize:clear.
  • Confirm .env database values and APP_KEY.
  • Confirm storage/ and bootstrap/cache are writable.

Menus are permission-aware. Check the user's role permissions. Admins should verify role assignment and permission cache. If permissions were changed through seeders, clear the permission cache through app tools or artisan cache clearing.

Email Not Sending

  • Send a test email from Settings.
  • Check SMTP host, port, encryption, username, password, from address, and timeout.
  • If using queued mail, confirm queue:work is running.
  • Check delivery logs and Laravel logs.

Scheduler Not Running

If SLA warnings, scheduled reports, or time-based automations are stale, check the server cron entry and the Operations Center heartbeats. For scheduled reports, run php artisan reports:send-scheduled manually once from the project root. If the manual command works but automatic delivery does not, the server cron for php artisan schedule:run is missing, using the wrong PHP path, or running under a user that cannot access the app files.

cPanel Cron and Queues

On shared cPanel hosting, configure cron from the private app directory. Adjust the PHP path and home path to match the host.

Laravel scheduler:

* * * * * /usr/local/bin/php /home/USER/supporthub/artisan schedule:run >> /dev/null 2>&1

Shared-host queue worker that exits after the queue is empty:

* * * * * /usr/local/bin/php /home/USER/supporthub/artisan queue:work --stop-when-empty --tries=3 --timeout=60 >> /dev/null 2>&1

If the host blocks long-running workers, use database or sync queue mode for first launch, then move high-volume mail and automation work to a host that supports workers or managed queues.

cPanel Package Checks

  • Private files should live in /home/USER/supporthub; public files should live in /home/USER/public_html/supporthub.
  • Do not upload .env, local screenshots, videos, logs, cache files, local uploads, tests, Node packages, or development tooling.
  • After extraction, visit /supporthub to run the fresh installer, then verify /supporthub/login.
  • Run Post-Install Verification, Health Export, Go-Live Readiness, Release Checklist acceptance, Demo Mail Center, and Delivery Diagnostics before a buyer demo.

Webhook Failures

Inspect failed deliveries in Platform Ops, confirm endpoint availability, verify expected signatures, and replay one failed delivery after the endpoint is fixed. Rotate webhook secrets if a secret may be exposed.

API Errors

  • 401 means missing, invalid, or inactive API token.
  • 403 means the client lacks the required scope.
  • 409 means an idempotency key was reused with a different payload.
  • 422 means validation failed; inspect the JSON validation errors.
PreviousNext